--- /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.1" />\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 short git tutorial</title>\r
+</head>\r
+<body>\r
+<div id="header">\r
+<h1>A short git tutorial</h1>\r
+</div>\r
+<h2>Introduction</h2>\r
+<div class="sectionbody">\r
+<p>This is trying to be a short tutorial on setting up and using a git\r
+repository, mainly because being hands-on and using explicit examples is\r
+often the best way of explaining what is going on.</p>\r
+<p>In normal life, most people wouldn't use the "core" git programs\r
+directly, but rather script around them to make them more palatable.\r
+Understanding the core git stuff may help some people get those scripts\r
+done, though, and it may also be instructive in helping people\r
+understand what it is that the higher-level helper scripts are actually\r
+doing.</p>\r
+<p>The core git is often called "plumbing", with the prettier user\r
+interfaces on top of it called "porcelain". You may not want to use the\r
+plumbing directly very often, but it can be good to know what the\r
+plumbing does for when the porcelain isn't flushing.</p>\r
+<p>The material presented here often goes deep describing how things\r
+work internally. If you are mostly interested in using git as a\r
+SCM, you can skip them during your first pass.</p>\r
+<div class="admonitionblock">\r
+<table><tr>\r
+<td class="icon">\r
+<div class="title">Note</div>\r
+</td>\r
+<td class="content">And those "too deep" descriptions are often marked as Note.</td>\r
+</tr></table>\r
+</div>\r
+<div class="admonitionblock">\r
+<table><tr>\r
+<td class="icon">\r
+<div class="title">Note</div>\r
+</td>\r
+<td class="content">If you are already familiar with another version control system,\r
+like CVS, you may want to take a look at\r
+<a href="everyday.html">Everyday GIT in 20 commands or so</a> first\r
+before reading this.</td>\r
+</tr></table>\r
+</div>\r
+</div>\r
+<h2>Creating a git repository</h2>\r
+<div class="sectionbody">\r
+<p>Creating a new git repository couldn't be easier: all git repositories start\r
+out empty, and the only thing you need to do is find yourself a\r
+subdirectory that you want to use as a working tree - either an empty\r
+one for a totally new project, or an existing working tree that you want\r
+to import into git.</p>\r
+<p>For our first example, we're going to start a totally new repository from\r
+scratch, with no pre-existing files, and we'll call it <tt>git-tutorial</tt>.\r
+To start up, create a subdirectory for it, change into that\r
+subdirectory, and initialize the git infrastructure with <tt>git-init-db</tt>:</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ mkdir git-tutorial\r
+$ cd git-tutorial\r
+$ git-init-db</tt></pre>\r
+</div></div>\r
+<p>to which git will reply</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>defaulting to local storage area</tt></pre>\r
+</div></div>\r
+<p>which is just git's way of saying that you haven't been doing anything\r
+strange, and that it will have created a local <tt>.git</tt> directory setup for\r
+your new project. You will now have a <tt>.git</tt> directory, and you can\r
+inspect that with <tt>ls</tt>. For your new empty project, it should show you\r
+three entries, among other things:</p>\r
+<ul>\r
+<li>\r
+<p>\r
+a symlink called <tt>HEAD</tt>, pointing to <tt>refs/heads/master</tt> (if your\r
+ platform does not have native symlinks, it is a file containing the\r
+ line "ref: refs/heads/master")\r
+</p>\r
+<p>Don't worry about the fact that the file that the <tt>HEAD</tt> link points to\r
+doesn't even exist yet — you haven't created the commit that will\r
+start your <tt>HEAD</tt> development branch yet.</p>\r
+</li>\r
+<li>\r
+<p>\r
+a subdirectory called <tt>objects</tt>, which will contain all the\r
+ objects of your project. You should never have any real reason to\r
+ look at the objects directly, but you might want to know that these\r
+ objects are what contains all the real <em>data</em> in your repository.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+a subdirectory called <tt>refs</tt>, which contains references to objects.\r
+</p>\r
+</li>\r
+</ul>\r
+<p>In particular, the <tt>refs</tt> subdirectory will contain two other\r
+subdirectories, named <tt>heads</tt> and <tt>tags</tt> respectively. They do\r
+exactly what their names imply: they contain references to any number\r
+of different <em>heads</em> of development (aka <em>branches</em>), and to any\r
+<em>tags</em> that you have created to name specific versions in your\r
+repository.</p>\r
+<p>One note: the special <tt>master</tt> head is the default branch, which is\r
+why the <tt>.git/HEAD</tt> file was created as a symlink to it even if it\r
+doesn't yet exist. Basically, the <tt>HEAD</tt> link is supposed to always\r
+point to the branch you are working on right now, and you always\r
+start out expecting to work on the <tt>master</tt> branch.</p>\r
+<p>However, this is only a convention, and you can name your branches\r
+anything you want, and don't have to ever even <em>have</em> a <tt>master</tt>\r
+branch. A number of the git tools will assume that <tt>.git/HEAD</tt> is\r
+valid, though.</p>\r
+<div class="admonitionblock">\r
+<table><tr>\r
+<td class="icon">\r
+<div class="title">Note</div>\r
+</td>\r
+<td class="content">An <em>object</em> is identified by its 160-bit SHA1 hash, aka <em>object name</em>,\r
+and a reference to an object is always the 40-byte hex\r
+representation of that SHA1 name. The files in the <tt>refs</tt>\r
+subdirectory are expected to contain these hex references\r
+(usually with a final <tt>'\n'</tt> at the end), and you should thus\r
+expect to see a number of 41-byte files containing these\r
+references in these <tt>refs</tt> subdirectories when you actually start\r
+populating your tree.</td>\r
+</tr></table>\r
+</div>\r
+<div class="admonitionblock">\r
+<table><tr>\r
+<td class="icon">\r
+<div class="title">Note</div>\r
+</td>\r
+<td class="content">An advanced user may want to take a look at the\r
+<a href="repository-layout.html">repository layout</a> document\r
+after finishing this tutorial.</td>\r
+</tr></table>\r
+</div>\r
+<p>You have now created your first git repository. Of course, since it's\r
+empty, that's not very useful, so let's start populating it with data.</p>\r
+</div>\r
+<h2>Populating a git repository</h2>\r
+<div class="sectionbody">\r
+<p>We'll keep this simple and stupid, so we'll start off with populating a\r
+few trivial files just to get a feel for it.</p>\r
+<p>Start off with just creating any random files that you want to maintain\r
+in your git repository. We'll start off with a few bad examples, just to\r
+get a feel for how this works:</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ echo "Hello World" >hello\r
+$ echo "Silly example" >example</tt></pre>\r
+</div></div>\r
+<p>you have now created two files in your working tree (aka <em>working directory</em>), but to\r
+actually check in your hard work, you will have to go through two steps:</p>\r
+<ul>\r
+<li>\r
+<p>\r
+fill in the <em>index</em> file (aka <em>cache</em>) with the information about your\r
+ working tree state.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+commit that index file as an object.\r
+</p>\r
+</li>\r
+</ul>\r
+<p>The first step is trivial: when you want to tell git about any changes\r
+to your working tree, you use the <tt>git-update-index</tt> program. That\r
+program normally just takes a list of filenames you want to update, but\r
+to avoid trivial mistakes, it refuses to add new entries to the index\r
+(or remove existing ones) unless you explicitly tell it that you're\r
+adding a new entry with the <tt>--add</tt> flag (or removing an entry with the\r
+<tt>--remove</tt>) flag.</p>\r
+<p>So to populate the index with the two files you just created, you can do</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ git-update-index --add hello example</tt></pre>\r
+</div></div>\r
+<p>and you have now told git to track those two files.</p>\r
+<p>In fact, as you did that, if you now look into your object directory,\r
+you'll notice that git will have added two new objects to the object\r
+database. If you did exactly the steps above, you should now be able to do</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ ls .git/objects/??/*</tt></pre>\r
+</div></div>\r
+<p>and see two files:</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>.git/objects/55/7db03de997c86a4a028e1ebd3a1ceb225be238\r
+.git/objects/f2/4c74a2e500f5ee1332c86b94199f52b1d1d962</tt></pre>\r
+</div></div>\r
+<p>which correspond with the objects with names of 557db… and f24c7..\r
+respectively.</p>\r
+<p>If you want to, you can use <tt>git-cat-file</tt> to look at those objects, but\r
+you'll have to use the object name, not the filename of the object:</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ git-cat-file -t 557db03de997c86a4a028e1ebd3a1ceb225be238</tt></pre>\r
+</div></div>\r
+<p>where the <tt>-t</tt> tells <tt>git-cat-file</tt> to tell you what the "type" of the\r
+object is. git will tell you that you have a "blob" object (ie just a\r
+regular file), and you can see the contents with</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ git-cat-file "blob" 557db03</tt></pre>\r
+</div></div>\r
+<p>which will print out "Hello World". The object 557db03 is nothing\r
+more than the contents of your file <tt>hello</tt>.</p>\r
+<div class="admonitionblock">\r
+<table><tr>\r
+<td class="icon">\r
+<div class="title">Note</div>\r
+</td>\r
+<td class="content">Don't confuse that object with the file <tt>hello</tt> itself. The\r
+object is literally just those specific <strong>contents</strong> of the file, and\r
+however much you later change the contents in file <tt>hello</tt>, the object\r
+we just looked at will never change. Objects are immutable.</td>\r
+</tr></table>\r
+</div>\r
+<div class="admonitionblock">\r
+<table><tr>\r
+<td class="icon">\r
+<div class="title">Note</div>\r
+</td>\r
+<td class="content">The second example demonstrates that you can\r
+abbreviate the object name to only the first several\r
+hexadecimal digits in most places.</td>\r
+</tr></table>\r
+</div>\r
+<p>Anyway, as we mentioned previously, you normally never actually take a\r
+look at the objects themselves, and typing long 40-character hex\r
+names is not something you'd normally want to do. The above digression\r
+was just to show that <tt>git-update-index</tt> did something magical, and\r
+actually saved away the contents of your files into the git object\r
+database.</p>\r
+<p>Updating the index did something else too: it created a <tt>.git/index</tt>\r
+file. This is the index that describes your current working tree, and\r
+something you should be very aware of. Again, you normally never worry\r
+about the index file itself, but you should be aware of the fact that\r
+you have not actually really "checked in" your files into git so far,\r
+you've only <strong>told</strong> git about them.</p>\r
+<p>However, since git knows about them, you can now start using some of the\r
+most basic git commands to manipulate the files or look at their status.</p>\r
+<p>In particular, let's not even check in the two files into git yet, we'll\r
+start off by adding another line to <tt>hello</tt> first:</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ echo "It's a new day for git" >>hello</tt></pre>\r
+</div></div>\r
+<p>and you can now, since you told git about the previous state of <tt>hello</tt>, ask\r
+git what has changed in the tree compared to your old index, using the\r
+<tt>git-diff-files</tt> command:</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ git-diff-files</tt></pre>\r
+</div></div>\r
+<p>Oops. That wasn't very readable. It just spit out its own internal\r
+version of a <tt>diff</tt>, but that internal version really just tells you\r
+that it has noticed that "hello" has been modified, and that the old object\r
+contents it had have been replaced with something else.</p>\r
+<p>To make it readable, we can tell git-diff-files to output the\r
+differences as a patch, using the <tt>-p</tt> flag:</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ git-diff-files -p\r
+diff --git a/hello b/hello\r
+index 557db03..263414f 100644\r
+--- a/hello\r
++++ b/hello\r
+@@ -1 +1,2 @@\r
+ Hello World\r
++It's a new day for git</tt></pre>\r
+</div></div>\r
+<p>i.e. the diff of the change we caused by adding another line to <tt>hello</tt>.</p>\r
+<p>In other words, <tt>git-diff-files</tt> always shows us the difference between\r
+what is recorded in the index, and what is currently in the working\r
+tree. That's very useful.</p>\r
+<p>A common shorthand for <tt>git-diff-files -p</tt> is to just write <tt>git\r
+diff</tt>, which will do the same thing.</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ git diff\r
+diff --git a/hello b/hello\r
+index 557db03..263414f 100644\r
+--- a/hello\r
++++ b/hello\r
+@@ -1 +1,2 @@\r
+ Hello World\r
++It's a new day for git</tt></pre>\r
+</div></div>\r
+</div>\r
+<h2>Committing git state</h2>\r
+<div class="sectionbody">\r
+<p>Now, we want to go to the next stage in git, which is to take the files\r
+that git knows about in the index, and commit them as a real tree. We do\r
+that in two phases: creating a <em>tree</em> object, and committing that <em>tree</em>\r
+object as a <em>commit</em> object together with an explanation of what the\r
+tree was all about, along with information of how we came to that state.</p>\r
+<p>Creating a tree object is trivial, and is done with <tt>git-write-tree</tt>.\r
+There are no options or other input: git-write-tree will take the\r
+current index state, and write an object that describes that whole\r
+index. In other words, we're now tying together all the different\r
+filenames with their contents (and their permissions), and we're\r
+creating the equivalent of a git "directory" object:</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ git-write-tree</tt></pre>\r
+</div></div>\r
+<p>and this will just output the name of the resulting tree, in this case\r
+(if you have done exactly as I've described) it should be</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>8988da15d077d4829fc51d8544c097def6644dbb</tt></pre>\r
+</div></div>\r
+<p>which is another incomprehensible object name. Again, if you want to,\r
+you can use <tt>git-cat-file -t 8988d...</tt> to see that this time the object\r
+is not a "blob" object, but a "tree" object (you can also use\r
+<tt>git-cat-file</tt> to actually output the raw object contents, but you'll see\r
+mainly a binary mess, so that's less interesting).</p>\r
+<p>However — normally you'd never use <tt>git-write-tree</tt> on its own, because\r
+normally you always commit a tree into a commit object using the\r
+<tt>git-commit-tree</tt> command. In fact, it's easier to not actually use\r
+<tt>git-write-tree</tt> on its own at all, but to just pass its result in as an\r
+argument to <tt>git-commit-tree</tt>.</p>\r
+<p><tt>git-commit-tree</tt> normally takes several arguments — it wants to know\r
+what the <em>parent</em> of a commit was, but since this is the first commit\r
+ever in this new repository, and it has no parents, we only need to pass in\r
+the object name of the tree. However, <tt>git-commit-tree</tt>\r
+also wants to get a commit message\r
+on its standard input, and it will write out the resulting object name for the\r
+commit to its standard output.</p>\r
+<p>And this is where we create the <tt>.git/refs/heads/master</tt> file\r
+which is pointed at by <tt>HEAD</tt>. This file is supposed to contain\r
+the reference to the top-of-tree of the master branch, and since\r
+that's exactly what <tt>git-commit-tree</tt> spits out, we can do this\r
+all with a sequence of simple shell commands:</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ tree=$(git-write-tree)\r
+$ commit=$(echo 'Initial commit' | git-commit-tree $tree)\r
+$ git-update-ref HEAD $commit</tt></pre>\r
+</div></div>\r
+<p>which will say:</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>Committing initial tree 8988da15d077d4829fc51d8544c097def6644dbb</tt></pre>\r
+</div></div>\r
+<p>just to warn you about the fact that it created a totally new commit\r
+that is not related to anything else. Normally you do this only <strong>once</strong>\r
+for a project ever, and all later commits will be parented on top of an\r
+earlier commit, and you'll never see this "Committing initial tree"\r
+message ever again.</p>\r
+<p>Again, normally you'd never actually do this by hand. There is a\r
+helpful script called <tt>git commit</tt> that will do all of this for you. So\r
+you could have just written <tt>git commit</tt>\r
+instead, and it would have done the above magic scripting for you.</p>\r
+</div>\r
+<h2>Making a change</h2>\r
+<div class="sectionbody">\r
+<p>Remember how we did the <tt>git-update-index</tt> on file <tt>hello</tt> and then we\r
+changed <tt>hello</tt> afterward, and could compare the new state of <tt>hello</tt> with the\r
+state we saved in the index file?</p>\r
+<p>Further, remember how I said that <tt>git-write-tree</tt> writes the contents\r
+of the <strong>index</strong> file to the tree, and thus what we just committed was in\r
+fact the <strong>original</strong> contents of the file <tt>hello</tt>, not the new ones. We did\r
+that on purpose, to show the difference between the index state, and the\r
+state in the working tree, and how they don't have to match, even\r
+when we commit things.</p>\r
+<p>As before, if we do <tt>git-diff-files -p</tt> in our git-tutorial project,\r
+we'll still see the same difference we saw last time: the index file\r
+hasn't changed by the act of committing anything. However, now that we\r
+have committed something, we can also learn to use a new command:\r
+<tt>git-diff-index</tt>.</p>\r
+<p>Unlike <tt>git-diff-files</tt>, which showed the difference between the index\r
+file and the working tree, <tt>git-diff-index</tt> shows the differences\r
+between a committed <strong>tree</strong> and either the index file or the working\r
+tree. In other words, <tt>git-diff-index</tt> wants a tree to be diffed\r
+against, and before we did the commit, we couldn't do that, because we\r
+didn't have anything to diff against.</p>\r
+<p>But now we can do</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ git-diff-index -p HEAD</tt></pre>\r
+</div></div>\r
+<p>(where <tt>-p</tt> has the same meaning as it did in <tt>git-diff-files</tt>), and it\r
+will show us the same difference, but for a totally different reason.\r
+Now we're comparing the working tree not against the index file,\r
+but against the tree we just wrote. It just so happens that those two\r
+are obviously the same, so we get the same result.</p>\r
+<p>Again, because this is a common operation, you can also just shorthand\r
+it with</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ git diff HEAD</tt></pre>\r
+</div></div>\r
+<p>which ends up doing the above for you.</p>\r
+<p>In other words, <tt>git-diff-index</tt> normally compares a tree against the\r
+working tree, but when given the <tt>--cached</tt> flag, it is told to\r
+instead compare against just the index cache contents, and ignore the\r
+current working tree state entirely. Since we just wrote the index\r
+file to HEAD, doing <tt>git-diff-index --cached -p HEAD</tt> should thus return\r
+an empty set of differences, and that's exactly what it does.</p>\r
+<div class="admonitionblock">\r
+<table><tr>\r
+<td class="icon">\r
+<div class="title">Note</div>\r
+</td>\r
+<td class="content">\r
+<p><tt>git-diff-index</tt> really always uses the index for its\r
+comparisons, and saying that it compares a tree against the working\r
+tree is thus not strictly accurate. In particular, the list of\r
+files to compare (the "meta-data") <strong>always</strong> comes from the index file,\r
+regardless of whether the <tt>--cached</tt> flag is used or not. The <tt>--cached</tt>\r
+flag really only determines whether the file <strong>contents</strong> to be compared\r
+come from the working tree or not.</p>\r
+<p>This is not hard to understand, as soon as you realize that git simply\r
+never knows (or cares) about files that it is not told about\r
+explicitly. git will never go <strong>looking</strong> for files to compare, it\r
+expects you to tell it what the files are, and that's what the index\r
+is there for.</p>\r
+</td>\r
+</tr></table>\r
+</div>\r
+<p>However, our next step is to commit the <strong>change</strong> we did, and again, to\r
+understand what's going on, keep in mind the difference between "working\r
+tree contents", "index file" and "committed tree". We have changes\r
+in the working tree that we want to commit, and we always have to\r
+work through the index file, so the first thing we need to do is to\r
+update the index cache:</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ git-update-index hello</tt></pre>\r
+</div></div>\r
+<p>(note how we didn't need the <tt>--add</tt> flag this time, since git knew\r
+about the file already).</p>\r
+<p>Note what happens to the different <tt>git-diff-*</tt> versions here. After\r
+we've updated <tt>hello</tt> in the index, <tt>git-diff-files -p</tt> now shows no\r
+differences, but <tt>git-diff-index -p HEAD</tt> still *does* show that the\r
+current state is different from the state we committed. In fact, now\r
+<tt>git-diff-index</tt> shows the same difference whether we use the <tt>—cached</tt>\r
+flag or not, since now the index is coherent with the working tree.</p>\r
+<p>Now, since we've updated <tt>hello</tt> in the index, we can commit the new\r
+version. We could do it by writing the tree by hand again, and\r
+committing the tree (this time we'd have to use the <tt>-p HEAD</tt> flag to\r
+tell commit that the HEAD was the <strong>parent</strong> of the new commit, and that\r
+this wasn't an initial commit any more), but you've done that once\r
+already, so let's just use the helpful script this time:</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ git commit</tt></pre>\r
+</div></div>\r
+<p>which starts an editor for you to write the commit message and tells you\r
+a bit about what you have done.</p>\r
+<p>Write whatever message you want, and all the lines that start with <em>#</em>\r
+will be pruned out, and the rest will be used as the commit message for\r
+the change. If you decide you don't want to commit anything after all at\r
+this point (you can continue to edit things and update the index), you\r
+can just leave an empty message. Otherwise <tt>git commit</tt> will commit\r
+the change for you.</p>\r
+<p>You've now made your first real git commit. And if you're interested in\r
+looking at what <tt>git commit</tt> really does, feel free to investigate:\r
+it's a few very simple shell scripts to generate the helpful (?) commit\r
+message headers, and a few one-liners that actually do the\r
+commit itself (<tt>git-commit</tt>).</p>\r
+</div>\r
+<h2>Inspecting Changes</h2>\r
+<div class="sectionbody">\r
+<p>While creating changes is useful, it's even more useful if you can tell\r
+later what changed. The most useful command for this is another of the\r
+<tt>diff</tt> family, namely <tt>git-diff-tree</tt>.</p>\r
+<p><tt>git-diff-tree</tt> can be given two arbitrary trees, and it will tell you the\r
+differences between them. Perhaps even more commonly, though, you can\r
+give it just a single commit object, and it will figure out the parent\r
+of that commit itself, and show the difference directly. Thus, to get\r
+the same diff that we've already seen several times, we can now do</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ git-diff-tree -p HEAD</tt></pre>\r
+</div></div>\r
+<p>(again, <tt>-p</tt> means to show the difference as a human-readable patch),\r
+and it will show what the last commit (in <tt>HEAD</tt>) actually changed.</p>\r
+<div class="admonitionblock">\r
+<table><tr>\r
+<td class="icon">\r
+<div class="title">Note</div>\r
+</td>\r
+<td class="content">\r
+<p>Here is an ASCII art by Jon Loeliger that illustrates how\r
+various diff-* commands compare things.</p>\r
+<div class="literalblock">\r
+<div class="content">\r
+<pre><tt> diff-tree\r
+ +----+\r
+ | |\r
+ | |\r
+ V V\r
+ +-----------+\r
+ | Object DB |\r
+ | Backing |\r
+ | Store |\r
+ +-----------+\r
+ ^ ^\r
+ | |\r
+ | | diff-index --cached\r
+ | |\r
+diff-index | V\r
+ | +-----------+\r
+ | | Index |\r
+ | | "cache" |\r
+ | +-----------+\r
+ | ^\r
+ | |\r
+ | | diff-files\r
+ | |\r
+ V V\r
+ +-----------+\r
+ | Working |\r
+ | Directory |\r
+ +-----------+</tt></pre>\r
+</div></div>\r
+</td>\r
+</tr></table>\r
+</div>\r
+<p>More interestingly, you can also give <tt>git-diff-tree</tt> the <tt>-v</tt> flag, which\r
+tells it to also show the commit message and author and date of the\r
+commit, and you can tell it to show a whole series of diffs.\r
+Alternatively, you can tell it to be "silent", and not show the diffs at\r
+all, but just show the actual commit message.</p>\r
+<p>In fact, together with the <tt>git-rev-list</tt> program (which generates a\r
+list of revisions), <tt>git-diff-tree</tt> ends up being a veritable fount of\r
+changes. A trivial (but very useful) script called <tt>git-whatchanged</tt> is\r
+included with git which does exactly this, and shows a log of recent\r
+activities.</p>\r
+<p>To see the whole history of our pitiful little git-tutorial project, you\r
+can do</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ git log</tt></pre>\r
+</div></div>\r
+<p>which shows just the log messages, or if we want to see the log together\r
+with the associated patches use the more complex (and much more\r
+powerful)</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ git-whatchanged -p --root</tt></pre>\r
+</div></div>\r
+<p>and you will see exactly what has changed in the repository over its\r
+short history.</p>\r
+<div class="admonitionblock">\r
+<table><tr>\r
+<td class="icon">\r
+<div class="title">Note</div>\r
+</td>\r
+<td class="content">The <tt>--root</tt> flag is a flag to <tt>git-diff-tree</tt> to tell it to\r
+show the initial aka <em>root</em> commit too. Normally you'd probably not\r
+want to see the initial import diff, but since the tutorial project\r
+was started from scratch and is so small, we use it to make the result\r
+a bit more interesting.</td>\r
+</tr></table>\r
+</div>\r
+<p>With that, you should now be having some inkling of what git does, and\r
+can explore on your own.</p>\r
+<div class="admonitionblock">\r
+<table><tr>\r
+<td class="icon">\r
+<div class="title">Note</div>\r
+</td>\r
+<td class="content">Most likely, you are not directly using the core\r
+git Plumbing commands, but using Porcelain like Cogito on top\r
+of it. Cogito works a bit differently and you usually do not\r
+have to run <tt>git-update-index</tt> yourself for changed files (you\r
+do tell underlying git about additions and removals via\r
+<tt>cg-add</tt> and <tt>cg-rm</tt> commands). Just before you make a commit\r
+with <tt>cg-commit</tt>, Cogito figures out which files you modified,\r
+and runs <tt>git-update-index</tt> on them for you.</td>\r
+</tr></table>\r
+</div>\r
+</div>\r
+<h2>Tagging a version</h2>\r
+<div class="sectionbody">\r
+<p>In git, there are two kinds of tags, a "light" one, and an "annotated tag".</p>\r
+<p>A "light" tag is technically nothing more than a branch, except we put\r
+it in the <tt>.git/refs/tags/</tt> subdirectory instead of calling it a <tt>head</tt>.\r
+So the simplest form of tag involves nothing more than</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ git tag my-first-tag</tt></pre>\r
+</div></div>\r
+<p>which just writes the current <tt>HEAD</tt> into the <tt>.git/refs/tags/my-first-tag</tt>\r
+file, after which point you can then use this symbolic name for that\r
+particular state. You can, for example, do</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ git diff my-first-tag</tt></pre>\r
+</div></div>\r
+<p>to diff your current state against that tag (which at this point will\r
+obviously be an empty diff, but if you continue to develop and commit\r
+stuff, you can use your tag as an "anchor-point" to see what has changed\r
+since you tagged it.</p>\r
+<p>An "annotated tag" is actually a real git object, and contains not only a\r
+pointer to the state you want to tag, but also a small tag name and\r
+message, along with optionally a PGP signature that says that yes,\r
+you really did\r
+that tag. You create these annotated tags with either the <tt>-a</tt> or\r
+<tt>-s</tt> flag to <tt>git tag</tt>:</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ git tag -s <tagname></tt></pre>\r
+</div></div>\r
+<p>which will sign the current <tt>HEAD</tt> (but you can also give it another\r
+argument that specifies the thing to tag, ie you could have tagged the\r
+current <tt>mybranch</tt> point by using <tt>git tag <tagname> mybranch</tt>).</p>\r
+<p>You normally only do signed tags for major releases or things\r
+like that, while the light-weight tags are useful for any marking you\r
+want to do — any time you decide that you want to remember a certain\r
+point, just create a private tag for it, and you have a nice symbolic\r
+name for the state at that point.</p>\r
+</div>\r
+<h2>Copying repositories</h2>\r
+<div class="sectionbody">\r
+<p>git repositories are normally totally self-sufficient and relocatable\r
+Unlike CVS, for example, there is no separate notion of\r
+"repository" and "working tree". A git repository normally <strong>is</strong> the\r
+working tree, with the local git information hidden in the <tt>.git</tt>\r
+subdirectory. There is nothing else. What you see is what you got.</p>\r
+<div class="admonitionblock">\r
+<table><tr>\r
+<td class="icon">\r
+<div class="title">Note</div>\r
+</td>\r
+<td class="content">You can tell git to split the git internal information from\r
+the directory that it tracks, but we'll ignore that for now: it's not\r
+how normal projects work, and it's really only meant for special uses.\r
+So the mental model of "the git information is always tied directly to\r
+the working tree that it describes" may not be technically 100%\r
+accurate, but it's a good model for all normal use.</td>\r
+</tr></table>\r
+</div>\r
+<p>This has two implications:</p>\r
+<ul>\r
+<li>\r
+<p>\r
+if you grow bored with the tutorial repository you created (or you've\r
+ made a mistake and want to start all over), you can just do simple\r
+</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ rm -rf git-tutorial</tt></pre>\r
+</div></div>\r
+<p>and it will be gone. There's no external repository, and there's no\r
+history outside the project you created.</p>\r
+</li>\r
+<li>\r
+<p>\r
+if you want to move or duplicate a git repository, you can do so. There\r
+ is <tt>git clone</tt> command, but if all you want to do is just to\r
+ create a copy of your repository (with all the full history that\r
+ went along with it), you can do so with a regular\r
+ <tt>cp -a git-tutorial new-git-tutorial</tt>.\r
+</p>\r
+<p>Note that when you've moved or copied a git repository, your git index\r
+file (which caches various information, notably some of the "stat"\r
+information for the files involved) will likely need to be refreshed.\r
+So after you do a <tt>cp -a</tt> to create a new copy, you'll want to do</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ git-update-index --refresh</tt></pre>\r
+</div></div>\r
+<p>in the new repository to make sure that the index file is up-to-date.</p>\r
+</li>\r
+</ul>\r
+<p>Note that the second point is true even across machines. You can\r
+duplicate a remote git repository with <strong>any</strong> regular copy mechanism, be it\r
+<tt>scp</tt>, <tt>rsync</tt> or <tt>wget</tt>.</p>\r
+<p>When copying a remote repository, you'll want to at a minimum update the\r
+index cache when you do this, and especially with other peoples'\r
+repositories you often want to make sure that the index cache is in some\r
+known state (you don't know <strong>what</strong> they've done and not yet checked in),\r
+so usually you'll precede the <tt>git-update-index</tt> with a</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ git-read-tree --reset HEAD\r
+$ git-update-index --refresh</tt></pre>\r
+</div></div>\r
+<p>which will force a total index re-build from the tree pointed to by <tt>HEAD</tt>.\r
+It resets the index contents to <tt>HEAD</tt>, and then the <tt>git-update-index</tt>\r
+makes sure to match up all index entries with the checked-out files.\r
+If the original repository had uncommitted changes in its\r
+working tree, <tt>git-update-index —refresh</tt> notices them and\r
+tells you they need to be updated.</p>\r
+<p>The above can also be written as simply</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ git reset</tt></pre>\r
+</div></div>\r
+<p>and in fact a lot of the common git command combinations can be scripted\r
+with the <tt>git xyz</tt> interfaces. You can learn things by just looking\r
+at what the various git scripts do. For example, <tt>git reset</tt> is the\r
+above two lines implemented in <tt>git-reset</tt>, but some things like\r
+<tt>git status</tt> and <tt>git commit</tt> are slightly more complex scripts around\r
+the basic git commands.</p>\r
+<p>Many (most?) public remote repositories will not contain any of\r
+the checked out files or even an index file, and will <strong>only</strong> contain the\r
+actual core git files. Such a repository usually doesn't even have the\r
+<tt>.git</tt> subdirectory, but has all the git files directly in the\r
+repository.</p>\r
+<p>To create your own local live copy of such a "raw" git repository, you'd\r
+first create your own subdirectory for the project, and then copy the\r
+raw repository contents into the <tt>.git</tt> directory. For example, to\r
+create your own copy of the git repository, you'd do the following</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ mkdir my-git\r
+$ cd my-git\r
+$ rsync -rL rsync://rsync.kernel.org/pub/scm/git/git.git/ .git</tt></pre>\r
+</div></div>\r
+<p>followed by</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ git-read-tree HEAD</tt></pre>\r
+</div></div>\r
+<p>to populate the index. However, now you have populated the index, and\r
+you have all the git internal files, but you will notice that you don't\r
+actually have any of the working tree files to work on. To get\r
+those, you'd check them out with</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ git-checkout-index -u -a</tt></pre>\r
+</div></div>\r
+<p>where the <tt>-u</tt> flag means that you want the checkout to keep the index\r
+up-to-date (so that you don't have to refresh it afterward), and the\r
+<tt>-a</tt> flag means "check out all files" (if you have a stale copy or an\r
+older version of a checked out tree you may also need to add the <tt>-f</tt>\r
+flag first, to tell git-checkout-index to <strong>force</strong> overwriting of any old\r
+files).</p>\r
+<p>Again, this can all be simplified with</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ git clone rsync://rsync.kernel.org/pub/scm/git/git.git/ my-git\r
+$ cd my-git\r
+$ git checkout</tt></pre>\r
+</div></div>\r
+<p>which will end up doing all of the above for you.</p>\r
+<p>You have now successfully copied somebody else's (mine) remote\r
+repository, and checked it out.</p>\r
+</div>\r
+<h2>Creating a new branch</h2>\r
+<div class="sectionbody">\r
+<p>Branches in git are really nothing more than pointers into the git\r
+object database from within the <tt>.git/refs/</tt> subdirectory, and as we\r
+already discussed, the <tt>HEAD</tt> branch is nothing but a symlink to one of\r
+these object pointers.</p>\r
+<p>You can at any time create a new branch by just picking an arbitrary\r
+point in the project history, and just writing the SHA1 name of that\r
+object into a file under <tt>.git/refs/heads/</tt>. You can use any filename you\r
+want (and indeed, subdirectories), but the convention is that the\r
+"normal" branch is called <tt>master</tt>. That's just a convention, though,\r
+and nothing enforces it.</p>\r
+<p>To show that as an example, let's go back to the git-tutorial repository we\r
+used earlier, and create a branch in it. You do that by simply just\r
+saying that you want to check out a new branch:</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ git checkout -b mybranch</tt></pre>\r
+</div></div>\r
+<p>will create a new branch based at the current <tt>HEAD</tt> position, and switch\r
+to it.</p>\r
+<div class="admonitionblock">\r
+<table><tr>\r
+<td class="icon">\r
+<div class="title">Note</div>\r
+</td>\r
+<td class="content">\r
+<p>If you make the decision to start your new branch at some\r
+other point in the history than the current <tt>HEAD</tt>, you can do so by\r
+just telling <tt>git checkout</tt> what the base of the checkout would be.\r
+In other words, if you have an earlier tag or branch, you'd just do</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ git checkout -b mybranch earlier-commit</tt></pre>\r
+</div></div>\r
+<p>and it would create the new branch <tt>mybranch</tt> at the earlier commit,\r
+and check out the state at that time.</p>\r
+</td>\r
+</tr></table>\r
+</div>\r
+<p>You can always just jump back to your original <tt>master</tt> branch by doing</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ git checkout master</tt></pre>\r
+</div></div>\r
+<p>(or any other branch-name, for that matter) and if you forget which\r
+branch you happen to be on, a simple</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ ls -l .git/HEAD</tt></pre>\r
+</div></div>\r
+<p>will tell you where it's pointing (Note that on platforms with bad or no\r
+symlink support, you have to execute</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ cat .git/HEAD</tt></pre>\r
+</div></div>\r
+<p>instead). To get the list of branches you have, you can say</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ git branch</tt></pre>\r
+</div></div>\r
+<p>which is nothing more than a simple script around <tt>ls .git/refs/heads</tt>.\r
+There will be asterisk in front of the branch you are currently on.</p>\r
+<p>Sometimes you may wish to create a new branch _without_ actually\r
+checking it out and switching to it. If so, just use the command</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ git branch <branchname> [startingpoint]</tt></pre>\r
+</div></div>\r
+<p>which will simply _create_ the branch, but will not do anything further.\r
+You can then later — once you decide that you want to actually develop\r
+on that branch — switch to that branch with a regular <tt>git checkout</tt>\r
+with the branchname as the argument.</p>\r
+</div>\r
+<h2>Merging two branches</h2>\r
+<div class="sectionbody">\r
+<p>One of the ideas of having a branch is that you do some (possibly\r
+experimental) work in it, and eventually merge it back to the main\r
+branch. So assuming you created the above <tt>mybranch</tt> that started out\r
+being the same as the original <tt>master</tt> branch, let's make sure we're in\r
+that branch, and do some work there.</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ git checkout mybranch\r
+$ echo "Work, work, work" >>hello\r
+$ git commit -m 'Some work.' hello</tt></pre>\r
+</div></div>\r
+<p>Here, we just added another line to <tt>hello</tt>, and we used a shorthand for\r
+doing both <tt>git-update-index hello</tt> and <tt>git commit</tt> by just giving the\r
+filename directly to <tt>git commit</tt>. The <tt>-m</tt> flag is to give the\r
+commit log message from the command line.</p>\r
+<p>Now, to make it a bit more interesting, let's assume that somebody else\r
+does some work in the original branch, and simulate that by going back\r
+to the master branch, and editing the same file differently there:</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ git checkout master</tt></pre>\r
+</div></div>\r
+<p>Here, take a moment to look at the contents of <tt>hello</tt>, and notice how they\r
+don't contain the work we just did in <tt>mybranch</tt> — because that work\r
+hasn't happened in the <tt>master</tt> branch at all. Then do</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ echo "Play, play, play" >>hello\r
+$ echo "Lots of fun" >>example\r
+$ git commit -m 'Some fun.' hello example</tt></pre>\r
+</div></div>\r
+<p>since the master branch is obviously in a much better mood.</p>\r
+<p>Now, you've got two branches, and you decide that you want to merge the\r
+work done. Before we do that, let's introduce a cool graphical tool that\r
+helps you view what's going on:</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ gitk --all</tt></pre>\r
+</div></div>\r
+<p>will show you graphically both of your branches (that's what the <tt>--all</tt>\r
+means: normally it will just show you your current <tt>HEAD</tt>) and their\r
+histories. You can also see exactly how they came to be from a common\r
+source.</p>\r
+<p>Anyway, let's exit <tt>gitk</tt> (<tt>^Q</tt> or the File menu), and decide that we want\r
+to merge the work we did on the <tt>mybranch</tt> branch into the <tt>master</tt>\r
+branch (which is currently our <tt>HEAD</tt> too). To do that, there's a nice\r
+script called <tt>git merge</tt>, which wants to know which branches you want\r
+to resolve and what the merge is all about:</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ git merge "Merge work in mybranch" HEAD mybranch</tt></pre>\r
+</div></div>\r
+<p>where the first argument is going to be used as the commit message if\r
+the merge can be resolved automatically.</p>\r
+<p>Now, in this case we've intentionally created a situation where the\r
+merge will need to be fixed up by hand, though, so git will do as much\r
+of it as it can automatically (which in this case is just merge the <tt>example</tt>\r
+file, which had no differences in the <tt>mybranch</tt> branch), and say:</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt> Trying really trivial in-index merge...\r
+ fatal: Merge requires file-level merging\r
+ Nope.\r
+ ...\r
+ Auto-merging hello\r
+ CONFLICT (content): Merge conflict in hello\r
+ Automatic merge failed/prevented; fix up by hand</tt></pre>\r
+</div></div>\r
+<p>which is way too verbose, but it basically tells you that it failed the\r
+really trivial merge ("Simple merge") and did an "Automatic merge"\r
+instead, but that too failed due to conflicts in <tt>hello</tt>.</p>\r
+<p>Not to worry. It left the (trivial) conflict in <tt>hello</tt> in the same form you\r
+should already be well used to if you've ever used CVS, so let's just\r
+open <tt>hello</tt> in our editor (whatever that may be), and fix it up somehow.\r
+I'd suggest just making it so that <tt>hello</tt> contains all four lines:</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>Hello World\r
+It's a new day for git\r
+Play, play, play\r
+Work, work, work</tt></pre>\r
+</div></div>\r
+<p>and once you're happy with your manual merge, just do a</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ git commit hello</tt></pre>\r
+</div></div>\r
+<p>which will very loudly warn you that you're now committing a merge\r
+(which is correct, so never mind), and you can write a small merge\r
+message about your adventures in git-merge-land.</p>\r
+<p>After you're done, start up <tt>gitk --all</tt> to see graphically what the\r
+history looks like. Notice that <tt>mybranch</tt> still exists, and you can\r
+switch to it, and continue to work with it if you want to. The\r
+<tt>mybranch</tt> branch will not contain the merge, but next time you merge it\r
+from the <tt>master</tt> branch, git will know how you merged it, so you'll not\r
+have to do _that_ merge again.</p>\r
+<p>Another useful tool, especially if you do not always work in X-Window\r
+environment, is <tt>git show-branch</tt>.</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ git show-branch master mybranch\r
+* [master] Merge work in mybranch\r
+ ! [mybranch] Some work.\r
+--\r
+- [master] Merge work in mybranch\r
+*+ [mybranch] Some work.</tt></pre>\r
+</div></div>\r
+<p>The first two lines indicate that it is showing the two branches\r
+and the first line of the commit log message from their\r
+top-of-the-tree commits, you are currently on <tt>master</tt> branch\r
+(notice the asterisk <tt><strong></tt> character), and the first column for\r
+the later output lines is used to show commits contained in the\r
+<tt>master</tt> branch, and the second column for the <tt>mybranch</tt>\r
+branch. Three commits are shown along with their log messages.\r
+All of them have non blank characters in the first column (<tt></strong></tt>\r
+shows an ordinary commit on the current branch, <tt>.</tt> is a merge commit), which\r
+means they are now part of the <tt>master</tt> branch. Only the "Some\r
+work" commit has the plus <tt>+</tt> character in the second column,\r
+because <tt>mybranch</tt> has not been merged to incorporate these\r
+commits from the master branch. The string inside brackets\r
+before the commit log message is a short name you can use to\r
+name the commit. In the above example, <em>master</em> and <em>mybranch</em>\r
+are branch heads. <em>master~1</em> is the first parent of <em>master</em>\r
+branch head. Please see <em>git-rev-parse</em> documentation if you\r
+see more complex cases.</p>\r
+<p>Now, let's pretend you are the one who did all the work in\r
+<tt>mybranch</tt>, and the fruit of your hard work has finally been merged\r
+to the <tt>master</tt> branch. Let's go back to <tt>mybranch</tt>, and run\r
+resolve to get the "upstream changes" back to your branch.</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ git checkout mybranch\r
+$ git merge "Merge upstream changes." HEAD master</tt></pre>\r
+</div></div>\r
+<p>This outputs something like this (the actual commit object names\r
+would be different)</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>Updating from ae3a2da... to a80b4aa....\r
+ example | 1 +\r
+ hello | 1 +\r
+ 2 files changed, 2 insertions(+), 0 deletions(-)</tt></pre>\r
+</div></div>\r
+<p>Because your branch did not contain anything more than what are\r
+already merged into the <tt>master</tt> branch, the resolve operation did\r
+not actually do a merge. Instead, it just updated the top of\r
+the tree of your branch to that of the <tt>master</tt> branch. This is\r
+often called <em>fast forward</em> merge.</p>\r
+<p>You can run <tt>gitk --all</tt> again to see how the commit ancestry\r
+looks like, or run <tt>show-branch</tt>, which tells you this.</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ git show-branch master mybranch\r
+! [master] Merge work in mybranch\r
+ * [mybranch] Merge work in mybranch\r
+--\r
+-- [master] Merge work in mybranch</tt></pre>\r
+</div></div>\r
+</div>\r
+<h2>Merging external work</h2>\r
+<div class="sectionbody">\r
+<p>It's usually much more common that you merge with somebody else than\r
+merging with your own branches, so it's worth pointing out that git\r
+makes that very easy too, and in fact, it's not that different from\r
+doing a <tt>git merge</tt>. In fact, a remote merge ends up being nothing\r
+more than "fetch the work from a remote repository into a temporary tag"\r
+followed by a <tt>git merge</tt>.</p>\r
+<p>Fetching from a remote repository is done by, unsurprisingly,\r
+<tt>git fetch</tt>:</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ git fetch <remote-repository></tt></pre>\r
+</div></div>\r
+<p>One of the following transports can be used to name the\r
+repository to download from:</p>\r
+<dl>\r
+<dt>\r
+Rsync\r
+</dt>\r
+<dd>\r
+<p>\r
+ <tt>rsync://remote.machine/path/to/repo.git/</tt>\r
+</p>\r
+<p>Rsync transport is usable for both uploading and downloading,\r
+but is completely unaware of what git does, and can produce\r
+unexpected results when you download from the public repository\r
+while the repository owner is uploading into it via <tt>rsync</tt>\r
+transport. Most notably, it could update the files under\r
+<tt>refs/</tt> which holds the object name of the topmost commits\r
+before uploading the files in <tt>objects/</tt> — the downloader would\r
+obtain head commit object name while that object itself is still\r
+not available in the repository. For this reason, it is\r
+considered deprecated.</p>\r
+</dd>\r
+<dt>\r
+SSH\r
+</dt>\r
+<dd>\r
+<p>\r
+ <tt>remote.machine:/path/to/repo.git/</tt> or\r
+</p>\r
+<p><tt>ssh://remote.machine/path/to/repo.git/</tt></p>\r
+<p>This transport can be used for both uploading and downloading,\r
+and requires you to have a log-in privilege over <tt>ssh</tt> to the\r
+remote machine. It finds out the set of objects the other side\r
+lacks by exchanging the head commits both ends have and\r
+transfers (close to) minimum set of objects. It is by far the\r
+most efficient way to exchange git objects between repositories.</p>\r
+</dd>\r
+<dt>\r
+Local directory\r
+</dt>\r
+<dd>\r
+<p>\r
+ <tt>/path/to/repo.git/</tt>\r
+</p>\r
+<p>This transport is the same as SSH transport but uses <tt>sh</tt> to run\r
+both ends on the local machine instead of running other end on\r
+the remote machine via <tt>ssh</tt>.</p>\r
+</dd>\r
+<dt>\r
+git Native\r
+</dt>\r
+<dd>\r
+<p>\r
+ <tt>git://remote.machine/path/to/repo.git/</tt>\r
+</p>\r
+<p>This transport was designed for anonymous downloading. Like SSH\r
+transport, it finds out the set of objects the downstream side\r
+lacks and transfers (close to) minimum set of objects.</p>\r
+</dd>\r
+<dt>\r
+HTTP(S)\r
+</dt>\r
+<dd>\r
+<p>\r
+ <tt>http://remote.machine/path/to/repo.git/</tt>\r
+</p>\r
+<p>Downloader from http and https URL\r
+first obtains the topmost commit object name from the remote site\r
+by looking at the specified refname under <tt>repo.git/refs/</tt> directory,\r
+and then tries to obtain the\r
+commit object by downloading from <tt>repo.git/objects/xx/xxx...</tt>\r
+using the object name of that commit object. Then it reads the\r
+commit object to find out its parent commits and the associate\r
+tree object; it repeats this process until it gets all the\r
+necessary objects. Because of this behaviour, they are\r
+sometimes also called <em>commit walkers</em>.</p>\r
+<p>The <em>commit walkers</em> are sometimes also called <em>dumb\r
+transports</em>, because they do not require any git aware smart\r
+server like git Native transport does. Any stock HTTP server\r
+that does not even support directory index would suffice. But\r
+you must prepare your repository with <tt>git-update-server-info</tt>\r
+to help dumb transport downloaders.</p>\r
+<p>There are (confusingly enough) <tt>git-ssh-fetch</tt> and <tt>git-ssh-upload</tt>\r
+programs, which are <em>commit walkers</em>; they outlived their\r
+usefulness when git Native and SSH transports were introduced,\r
+and not used by <tt>git pull</tt> or <tt>git push</tt> scripts.</p>\r
+</dd>\r
+</dl>\r
+<p>Once you fetch from the remote repository, you <tt>resolve</tt> that\r
+with your current branch.</p>\r
+<p>However — it's such a common thing to <tt>fetch</tt> and then\r
+immediately <tt>resolve</tt>, that it's called <tt>git pull</tt>, and you can\r
+simply do</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ git pull <remote-repository></tt></pre>\r
+</div></div>\r
+<p>and optionally give a branch-name for the remote end as a second\r
+argument.</p>\r
+<div class="admonitionblock">\r
+<table><tr>\r
+<td class="icon">\r
+<div class="title">Note</div>\r
+</td>\r
+<td class="content">You could do without using any branches at all, by\r
+keeping as many local repositories as you would like to have\r
+branches, and merging between them with <tt>git pull</tt>, just like\r
+you merge between branches. The advantage of this approach is\r
+that it lets you keep set of files for each <tt>branch</tt> checked\r
+out and you may find it easier to switch back and forth if you\r
+juggle multiple lines of development simultaneously. Of\r
+course, you will pay the price of more disk usage to hold\r
+multiple working trees, but disk space is cheap these days.</td>\r
+</tr></table>\r
+</div>\r
+<div class="admonitionblock">\r
+<table><tr>\r
+<td class="icon">\r
+<div class="title">Note</div>\r
+</td>\r
+<td class="content">You could even pull from your own repository by\r
+giving <em>.</em> as <remote-repository> parameter to <tt>git pull</tt>. This\r
+is useful when you want to merge a local branch (or more, if you\r
+are making an Octopus) into the current branch.</td>\r
+</tr></table>\r
+</div>\r
+<p>It is likely that you will be pulling from the same remote\r
+repository from time to time. As a short hand, you can store\r
+the remote repository URL in a file under .git/remotes/\r
+directory, like this:</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ mkdir -p .git/remotes/\r
+$ cat >.git/remotes/linus <<\EOF\r
+URL: http://www.kernel.org/pub/scm/git/git.git/\r
+EOF</tt></pre>\r
+</div></div>\r
+<p>and use the filename to <tt>git pull</tt> instead of the full URL.\r
+The URL specified in such file can even be a prefix\r
+of a full URL, like this:</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ cat >.git/remotes/jgarzik <<\EOF\r
+URL: http://www.kernel.org/pub/scm/linux/git/jgarzik/\r
+EOF</tt></pre>\r
+</div></div>\r
+<p>Examples.</p>\r
+<ol>\r
+<li>\r
+<p>\r
+<tt>git pull linus</tt>\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+<tt>git pull linus tag v0.99.1</tt>\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+<tt>git pull jgarzik/netdev-2.6.git/ e100</tt>\r
+</p>\r
+</li>\r
+</ol>\r
+<p>the above are equivalent to:</p>\r
+<ol>\r
+<li>\r
+<p>\r
+<tt>git pull http://www.kernel.org/pub/scm/git/git.git/ HEAD</tt>\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+<tt>git pull http://www.kernel.org/pub/scm/git/git.git/ tag v0.99.1</tt>\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+<tt>git pull http://www.kernel.org/pub/…/jgarzik/netdev-2.6.git e100</tt>\r
+</p>\r
+</li>\r
+</ol>\r
+</div>\r
+<h2>How does the merge work?</h2>\r
+<div class="sectionbody">\r
+<p>We said this tutorial shows what plumbing does to help you cope\r
+with the porcelain that isn't flushing, but we so far did not\r
+talk about how the merge really works. If you are following\r
+this tutorial the first time, I'd suggest to skip to "Publishing\r
+your work" section and come back here later.</p>\r
+<p>OK, still with me? To give us an example to look at, let's go\r
+back to the earlier repository with "hello" and "example" file,\r
+and bring ourselves back to the pre-merge state:</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ git show-branch --more=3 master mybranch\r
+! [master] Merge work in mybranch\r
+ * [mybranch] Merge work in mybranch\r
+--\r
+-- [master] Merge work in mybranch\r
++* [master^2] Some work.\r
++* [master^] Some fun.</tt></pre>\r
+</div></div>\r
+<p>Remember, before running <tt>git merge</tt>, our <tt>master</tt> head was at\r
+"Some fun." commit, while our <tt>mybranch</tt> head was at "Some\r
+work." commit.</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ git checkout mybranch\r
+$ git reset --hard master^2\r
+$ git checkout master\r
+$ git reset --hard master^</tt></pre>\r
+</div></div>\r
+<p>After rewinding, the commit structure should look like this:</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ git show-branch\r
+* [master] Some fun.\r
+ ! [mybranch] Some work.\r
+--\r
+ + [mybranch] Some work.\r
+* [master] Some fun.\r
+*+ [mybranch^] New day.</tt></pre>\r
+</div></div>\r
+<p>Now we are ready to experiment with the merge by hand.</p>\r
+<p><tt>git merge</tt> command, when merging two branches, uses 3-way merge\r
+algorithm. First, it finds the common ancestor between them.\r
+The command it uses is <tt>git-merge-base</tt>:</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ mb=$(git-merge-base HEAD mybranch)</tt></pre>\r
+</div></div>\r
+<p>The command writes the commit object name of the common ancestor\r
+to the standard output, so we captured its output to a variable,\r
+because we will be using it in the next step. BTW, the common\r
+ancestor commit is the "New day." commit in this case. You can\r
+tell it by:</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ git-name-rev $mb\r
+my-first-tag</tt></pre>\r
+</div></div>\r
+<p>After finding out a common ancestor commit, the second step is\r
+this:</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ git-read-tree -m -u $mb HEAD mybranch</tt></pre>\r
+</div></div>\r
+<p>This is the same <tt>git-read-tree</tt> command we have already seen,\r
+but it takes three trees, unlike previous examples. This reads\r
+the contents of each tree into different <em>stage</em> in the index\r
+file (the first tree goes to stage 1, the second stage 2,\r
+etc.). After reading three trees into three stages, the paths\r
+that are the same in all three stages are <em>collapsed</em> into stage\r
+0. Also paths that are the same in two of three stages are\r
+collapsed into stage 0, taking the SHA1 from either stage 2 or\r
+stage 3, whichever is different from stage 1 (i.e. only one side\r
+changed from the common ancestor).</p>\r
+<p>After <em>collapsing</em> operation, paths that are different in three\r
+trees are left in non-zero stages. At this point, you can\r
+inspect the index file with this command:</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ git-ls-files --stage\r
+100644 7f8b141b65fdcee47321e399a2598a235a032422 0 example\r
+100644 263414f423d0e4d70dae8fe53fa34614ff3e2860 1 hello\r
+100644 06fa6a24256dc7e560efa5687fa84b51f0263c3a 2 hello\r
+100644 cc44c73eb783565da5831b4d820c962954019b69 3 hello</tt></pre>\r
+</div></div>\r
+<p>In our example of only two files, we did not have unchanged\r
+files so only <em>example</em> resulted in collapsing, but in real-life\r
+large projects, only small number of files change in one commit,\r
+and this <em>collapsing</em> tends to trivially merge most of the paths\r
+fairly quickly, leaving only a handful the real changes in non-zero\r
+stages.</p>\r
+<p>To look at only non-zero stages, use <tt>--unmerged</tt> flag:</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ git-ls-files --unmerged\r
+100644 263414f423d0e4d70dae8fe53fa34614ff3e2860 1 hello\r
+100644 06fa6a24256dc7e560efa5687fa84b51f0263c3a 2 hello\r
+100644 cc44c73eb783565da5831b4d820c962954019b69 3 hello</tt></pre>\r
+</div></div>\r
+<p>The next step of merging is to merge these three versions of the\r
+file, using 3-way merge. This is done by giving\r
+<tt>git-merge-one-file</tt> command as one of the arguments to\r
+<tt>git-merge-index</tt> command:</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ git-merge-index git-merge-one-file hello\r
+Auto-merging hello.\r
+merge: warning: conflicts during merge\r
+ERROR: Merge conflict in hello.\r
+fatal: merge program failed</tt></pre>\r
+</div></div>\r
+<p><tt>git-merge-one-file</tt> script is called with parameters to\r
+describe those three versions, and is responsible to leave the\r
+merge results in the working tree.\r
+It is a fairly straightforward shell script, and\r
+eventually calls <tt>merge</tt> program from RCS suite to perform a\r
+file-level 3-way merge. In this case, <tt>merge</tt> detects\r
+conflicts, and the merge result with conflict marks is left in\r
+the working tree.. This can be seen if you run <tt>ls-files\r
+—stage</tt> again at this point:</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ git-ls-files --stage\r
+100644 7f8b141b65fdcee47321e399a2598a235a032422 0 example\r
+100644 263414f423d0e4d70dae8fe53fa34614ff3e2860 1 hello\r
+100644 06fa6a24256dc7e560efa5687fa84b51f0263c3a 2 hello\r
+100644 cc44c73eb783565da5831b4d820c962954019b69 3 hello</tt></pre>\r
+</div></div>\r
+<p>This is the state of the index file and the working file after\r
+<tt>git merge</tt> returns control back to you, leaving the conflicting\r
+merge for you to resolve. Notice that the path <tt>hello</tt> is still\r
+unmerged, and what you see with <tt>git diff</tt> at this point is\r
+differences since stage 2 (i.e. your version).</p>\r
+</div>\r
+<h2>Publishing your work</h2>\r
+<div class="sectionbody">\r
+<p>So we can use somebody else's work from a remote repository; but\r
+how can <strong>you</strong> prepare a repository to let other people pull from\r
+it?</p>\r
+<p>Your do your real work in your working tree that has your\r
+primary repository hanging under it as its <tt>.git</tt> subdirectory.\r
+You <strong>could</strong> make that repository accessible remotely and ask\r
+people to pull from it, but in practice that is not the way\r
+things are usually done. A recommended way is to have a public\r
+repository, make it reachable by other people, and when the\r
+changes you made in your primary working tree are in good shape,\r
+update the public repository from it. This is often called\r
+<em>pushing</em>.</p>\r
+<div class="admonitionblock">\r
+<table><tr>\r
+<td class="icon">\r
+<div class="title">Note</div>\r
+</td>\r
+<td class="content">This public repository could further be mirrored, and that is\r
+how git repositories at <tt>kernel.org</tt> are managed.</td>\r
+</tr></table>\r
+</div>\r
+<p>Publishing the changes from your local (private) repository to\r
+your remote (public) repository requires a write privilege on\r
+the remote machine. You need to have an SSH account there to\r
+run a single command, <tt>git-receive-pack</tt>.</p>\r
+<p>First, you need to create an empty repository on the remote\r
+machine that will house your public repository. This empty\r
+repository will be populated and be kept up-to-date by pushing\r
+into it later. Obviously, this repository creation needs to be\r
+done only once.</p>\r
+<div class="admonitionblock">\r
+<table><tr>\r
+<td class="icon">\r
+<div class="title">Note</div>\r
+</td>\r
+<td class="content"><tt>git push</tt> uses a pair of programs,\r
+<tt>git-send-pack</tt> on your local machine, and <tt>git-receive-pack</tt>\r
+on the remote machine. The communication between the two over\r
+the network internally uses an SSH connection.</td>\r
+</tr></table>\r
+</div>\r
+<p>Your private repository's git directory is usually <tt>.git</tt>, but\r
+your public repository is often named after the project name,\r
+i.e. <tt><project>.git</tt>. Let's create such a public repository for\r
+project <tt>my-git</tt>. After logging into the remote machine, create\r
+an empty directory:</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ mkdir my-git.git</tt></pre>\r
+</div></div>\r
+<p>Then, make that directory into a git repository by running\r
+<tt>git init-db</tt>, but this time, since its name is not the usual\r
+<tt>.git</tt>, we do things slightly differently:</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ GIT_DIR=my-git.git git-init-db</tt></pre>\r
+</div></div>\r
+<p>Make sure this directory is available for others you want your\r
+changes to be pulled by via the transport of your choice. Also\r
+you need to make sure that you have the <tt>git-receive-pack</tt>\r
+program on the <tt>$PATH</tt>.</p>\r
+<div class="admonitionblock">\r
+<table><tr>\r
+<td class="icon">\r
+<div class="title">Note</div>\r
+</td>\r
+<td class="content">Many installations of sshd do not invoke your shell as the login\r
+shell when you directly run programs; what this means is that if\r
+your login shell is <tt>bash</tt>, only <tt>.bashrc</tt> is read and not\r
+<tt>.bash_profile</tt>. As a workaround, make sure <tt>.bashrc</tt> sets up\r
+<tt>$PATH</tt> so that you can run <tt>git-receive-pack</tt> program.</td>\r
+</tr></table>\r
+</div>\r
+<div class="admonitionblock">\r
+<table><tr>\r
+<td class="icon">\r
+<div class="title">Note</div>\r
+</td>\r
+<td class="content">If you plan to publish this repository to be accessed over http,\r
+you should do <tt>chmod +x my-git.git/hooks/post-update</tt> at this\r
+point. This makes sure that every time you push into this\r
+repository, <tt>git-update-server-info</tt> is run.</td>\r
+</tr></table>\r
+</div>\r
+<p>Your "public repository" is now ready to accept your changes.\r
+Come back to the machine you have your private repository. From\r
+there, run this command:</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ git push <public-host>:/path/to/my-git.git master</tt></pre>\r
+</div></div>\r
+<p>This synchronizes your public repository to match the named\r
+branch head (i.e. <tt>master</tt> in this case) and objects reachable\r
+from them in your current repository.</p>\r
+<p>As a real example, this is how I update my public git\r
+repository. Kernel.org mirror network takes care of the\r
+propagation to other publicly visible machines:</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ git push master.kernel.org:/pub/scm/git/git.git/</tt></pre>\r
+</div></div>\r
+</div>\r
+<h2>Packing your repository</h2>\r
+<div class="sectionbody">\r
+<p>Earlier, we saw that one file under <tt>.git/objects/??/</tt> directory\r
+is stored for each git object you create. This representation\r
+is efficient to create atomically and safely, but\r
+not so convenient to transport over the network. Since git objects are\r
+immutable once they are created, there is a way to optimize the\r
+storage by "packing them together". The command</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ git repack</tt></pre>\r
+</div></div>\r
+<p>will do it for you. If you followed the tutorial examples, you\r
+would have accumulated about 17 objects in <tt>.git/objects/??/</tt>\r
+directories by now. <tt>git repack</tt> tells you how many objects it\r
+packed, and stores the packed file in <tt>.git/objects/pack</tt>\r
+directory.</p>\r
+<div class="admonitionblock">\r
+<table><tr>\r
+<td class="icon">\r
+<div class="title">Note</div>\r
+</td>\r
+<td class="content">You will see two files, <tt>pack-*.pack</tt> and <tt>pack-*.idx</tt>,\r
+in <tt>.git/objects/pack</tt> directory. They are closely related to\r
+each other, and if you ever copy them by hand to a different\r
+repository for whatever reason, you should make sure you copy\r
+them together. The former holds all the data from the objects\r
+in the pack, and the latter holds the index for random\r
+access.</td>\r
+</tr></table>\r
+</div>\r
+<p>If you are paranoid, running <tt>git-verify-pack</tt> command would\r
+detect if you have a corrupt pack, but do not worry too much.\r
+Our programs are always perfect ;-).</p>\r
+<p>Once you have packed objects, you do not need to leave the\r
+unpacked objects that are contained in the pack file anymore.</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ git prune-packed</tt></pre>\r
+</div></div>\r
+<p>would remove them for you.</p>\r
+<p>You can try running <tt>find .git/objects -type f</tt> before and after\r
+you run <tt>git prune-packed</tt> if you are curious. Also <tt>git\r
+count-objects</tt> would tell you how many unpacked objects are in\r
+your repository and how much space they are consuming.</p>\r
+<div class="admonitionblock">\r
+<table><tr>\r
+<td class="icon">\r
+<div class="title">Note</div>\r
+</td>\r
+<td class="content"><tt>git pull</tt> is slightly cumbersome for HTTP transport, as a\r
+packed repository may contain relatively few objects in a\r
+relatively large pack. If you expect many HTTP pulls from your\r
+public repository you might want to repack & prune often, or\r
+never.</td>\r
+</tr></table>\r
+</div>\r
+<p>If you run <tt>git repack</tt> again at this point, it will say\r
+"Nothing to pack". Once you continue your development and\r
+accumulate the changes, running <tt>git repack</tt> again will create a\r
+new pack, that contains objects created since you packed your\r
+repository the last time. We recommend that you pack your project\r
+soon after the initial import (unless you are starting your\r
+project from scratch), and then run <tt>git repack</tt> every once in a\r
+while, depending on how active your project is.</p>\r
+<p>When a repository is synchronized via <tt>git push</tt> and <tt>git pull</tt>\r
+objects packed in the source repository are usually stored\r
+unpacked in the destination, unless rsync transport is used.\r
+While this allows you to use different packing strategies on\r
+both ends, it also means you may need to repack both\r
+repositories every once in a while.</p>\r
+</div>\r
+<h2>Working with Others</h2>\r
+<div class="sectionbody">\r
+<p>Although git is a truly distributed system, it is often\r
+convenient to organize your project with an informal hierarchy\r
+of developers. Linux kernel development is run this way. There\r
+is a nice illustration (page 17, "Merges to Mainline") in Randy\r
+Dunlap's presentation (<tt>http://tinyurl.com/a2jdg</tt>).</p>\r
+<p>It should be stressed that this hierarchy is purely <strong>informal</strong>.\r
+There is nothing fundamental in git that enforces the "chain of\r
+patch flow" this hierarchy implies. You do not have to pull\r
+from only one remote repository.</p>\r
+<p>A recommended workflow for a "project lead" goes like this:</p>\r
+<ol>\r
+<li>\r
+<p>\r
+Prepare your primary repository on your local machine. Your\r
+ work is done there.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+Prepare a public repository accessible to others.\r
+</p>\r
+<p>If other people are pulling from your repository over dumb\r
+transport protocols (HTTP), you need to keep this repository\r
+<em>dumb transport friendly</em>. After <tt>git init-db</tt>,\r
+<tt>$GIT_DIR/hooks/post-update</tt> copied from the standard templates\r
+would contain a call to <tt>git-update-server-info</tt> but the\r
+<tt>post-update</tt> hook itself is disabled by default — enable it\r
+with <tt>chmod +x post-update</tt>. This makes sure <tt>git-update-server-info</tt>\r
+keeps the necessary files up-to-date.</p>\r
+</li>\r
+<li>\r
+<p>\r
+Push into the public repository from your primary\r
+ repository.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+<tt>git repack</tt> the public repository. This establishes a big\r
+ pack that contains the initial set of objects as the\r
+ baseline, and possibly <tt>git prune</tt> if the transport\r
+ used for pulling from your repository supports packed\r
+ repositories.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+Keep working in your primary repository. Your changes\r
+ include modifications of your own, patches you receive via\r
+ e-mails, and merges resulting from pulling the "public"\r
+ repositories of your "subsystem maintainers".\r
+</p>\r
+<p>You can repack this private repository whenever you feel like.</p>\r
+</li>\r
+<li>\r
+<p>\r
+Push your changes to the public repository, and announce it\r
+ to the public.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+Every once in a while, "git repack" the public repository.\r
+ Go back to step 5. and continue working.\r
+</p>\r
+</li>\r
+</ol>\r
+<p>A recommended work cycle for a "subsystem maintainer" who works\r
+on that project and has an own "public repository" goes like this:</p>\r
+<ol>\r
+<li>\r
+<p>\r
+Prepare your work repository, by <tt>git clone</tt> the public\r
+ repository of the "project lead". The URL used for the\r
+ initial cloning is stored in <tt>.git/remotes/origin</tt>.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+Prepare a public repository accessible to others, just like\r
+ the "project lead" person does.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+Copy over the packed files from "project lead" public\r
+ repository to your public repository, unless the "project\r
+ lead" repository lives on the same machine as yours. In the\r
+ latter case, you can use <tt>objects/info/alternates</tt> file to\r
+ point at the repository you are borrowing from.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+Push into the public repository from your primary\r
+ repository. Run <tt>git repack</tt>, and possibly <tt>git prune</tt> if the\r
+ transport used for pulling from your repository supports\r
+ packed repositories.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+Keep working in your primary repository. Your changes\r
+ include modifications of your own, patches you receive via\r
+ e-mails, and merges resulting from pulling the "public"\r
+ repositories of your "project lead" and possibly your\r
+ "sub-subsystem maintainers".\r
+</p>\r
+<p>You can repack this private repository whenever you feel\r
+like.</p>\r
+</li>\r
+<li>\r
+<p>\r
+Push your changes to your public repository, and ask your\r
+ "project lead" and possibly your "sub-subsystem\r
+ maintainers" to pull from it.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+Every once in a while, <tt>git repack</tt> the public repository.\r
+ Go back to step 5. and continue working.\r
+</p>\r
+</li>\r
+</ol>\r
+<p>A recommended work cycle for an "individual developer" who does\r
+not have a "public" repository is somewhat different. It goes\r
+like this:</p>\r
+<ol>\r
+<li>\r
+<p>\r
+Prepare your work repository, by <tt>git clone</tt> the public\r
+ repository of the "project lead" (or a "subsystem\r
+ maintainer", if you work on a subsystem). The URL used for\r
+ the initial cloning is stored in <tt>.git/remotes/origin</tt>.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+Do your work in your repository on <em>master</em> branch.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+Run <tt>git fetch origin</tt> from the public repository of your\r
+ upstream every once in a while. This does only the first\r
+ half of <tt>git pull</tt> but does not merge. The head of the\r
+ public repository is stored in <tt>.git/refs/heads/origin</tt>.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+Use <tt>git cherry origin</tt> to see which ones of your patches\r
+ were accepted, and/or use <tt>git rebase origin</tt> to port your\r
+ unmerged changes forward to the updated upstream.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+Use <tt>git format-patch origin</tt> to prepare patches for e-mail\r
+ submission to your upstream and send it out. Go back to\r
+ step 2. and continue.\r
+</p>\r
+</li>\r
+</ol>\r
+</div>\r
+<h2>Working with Others, Shared Repository Style</h2>\r
+<div class="sectionbody">\r
+<p>If you are coming from CVS background, the style of cooperation\r
+suggested in the previous section may be new to you. You do not\r
+have to worry. git supports "shared public repository" style of\r
+cooperation you are probably more familiar with as well.</p>\r
+<p>For this, set up a public repository on a machine that is\r
+reachable via SSH by people with "commit privileges". Put the\r
+committers in the same user group and make the repository\r
+writable by that group. Make sure their umasks are set up to\r
+allow group members to write into directories other members\r
+have created.</p>\r
+<p>You, as an individual committer, then:</p>\r
+<ul>\r
+<li>\r
+<p>\r
+First clone the shared repository to a local repository:\r
+</p>\r
+</li>\r
+</ul>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ git clone repo.shared.xz:/pub/scm/project.git/ my-project\r
+$ cd my-project\r
+$ hack away</tt></pre>\r
+</div></div>\r
+<ul>\r
+<li>\r
+<p>\r
+Merge the work others might have done while you were hacking\r
+ away:\r
+</p>\r
+</li>\r
+</ul>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ git pull origin\r
+$ test the merge result</tt></pre>\r
+</div></div>\r
+<div class="admonitionblock">\r
+<table><tr>\r
+<td class="icon">\r
+<div class="title">Note</div>\r
+</td>\r
+<td class="content">\r
+<p>The first <tt>git clone</tt> would have placed the following in\r
+<tt>my-project/.git/remotes/origin</tt> file, and that's why this and\r
+the next step work.</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>URL: repo.shared.xz:/pub/scm/project.git/ my-project\r
+Pull: master:origin</tt></pre>\r
+</div></div>\r
+</td>\r
+</tr></table>\r
+</div>\r
+<ul>\r
+<li>\r
+<p>\r
+push your work as the new head of the shared\r
+ repository.\r
+</p>\r
+</li>\r
+</ul>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ git push origin master</tt></pre>\r
+</div></div>\r
+<p>If somebody else pushed into the same shared repository while\r
+you were working locally, <tt>git push</tt> in the last step would\r
+complain, telling you that the remote <tt>master</tt> head does not\r
+fast forward. You need to pull and merge those other changes\r
+back before you push your work when it happens.</p>\r
+<p>The <tt>git push</tt> command without any explicit refspec parameter\r
+pushes the refs that exist both in the local repository and the\r
+remote repository. So the last <tt>push</tt> can be done with either\r
+one of these:</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ git push origin\r
+$ git push repo.shared.xz:/pub/scm/project.git/</tt></pre>\r
+</div></div>\r
+<p>as long as the shared repository does not have any branches\r
+other than <tt>master</tt>.\r
+[NOTE]</p>\r
+<div class="exampleblock">\r
+<div class="exampleblock-content">\r
+<p>If you created your shared repository by cloning from somewhere\r
+else, you may have the <tt>origin</tt> branch. Your developers\r
+typically do not use that branch; remove it. Otherwise, that\r
+would be pushed back by the <tt>git push origin</tt> because your\r
+developers' repository would surely have <tt>origin</tt> branch to keep\r
+track of the shared repository, and would be counted as "exist\r
+on both ends".</p>\r
+</div></div>\r
+</div>\r
+<h2>Advanced Shared Repository Management</h2>\r
+<div class="sectionbody">\r
+<p>Being able to push into a shared repository means being able to\r
+write into it. If your developers are coming over the network,\r
+this means you, as the repository administrator, need to give\r
+each of them an SSH access to the shared repository machine.</p>\r
+<p>In some cases, though, you may not want to give a normal shell\r
+account to them, but want to restrict them to be able to only\r
+do <tt>git push</tt> into the repository and nothing else.</p>\r
+<p>You can achieve this by setting the login shell of your\r
+developers on the shared repository host to <tt>git-shell</tt> program.</p>\r
+<div class="admonitionblock">\r
+<table><tr>\r
+<td class="icon">\r
+<div class="title">Note</div>\r
+</td>\r
+<td class="content">Most likely you would also need to list <tt>git-shell</tt> program in\r
+<tt>/etc/shells</tt> file.</td>\r
+</tr></table>\r
+</div>\r
+<p>This restricts the set of commands that can be run from incoming\r
+SSH connection for these users to only <tt>receive-pack</tt> and\r
+<tt>upload-pack</tt>, so the only thing they can do are <tt>git fetch</tt> and\r
+<tt>git push</tt>.</p>\r
+<p>You still need to create UNIX user accounts for each developer,\r
+and put them in the same group. Make sure that the repository\r
+shared among these developers is writable by that group.</p>\r
+<ol>\r
+<li>\r
+<p>\r
+Initializing the shared repository with <tt>git-init-db —shared</tt>\r
+helps somewhat.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+Run the following in the shared repository:\r
+</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ chgrp -R $group repo.git\r
+$ find repo.git -type d -print | xargs chmod ug+rwx,g+s\r
+$ GIT_DIR=repo.git git repo-config core.sharedrepository true</tt></pre>\r
+</div></div>\r
+</li>\r
+</ol>\r
+<p>The above measures make sure that directories lazily created in\r
+<tt>$GIT_DIR</tt> are writable by group members. You, as the\r
+repository administrator, are still responsible to make sure\r
+your developers belong to that shared repository group and set\r
+their umask to a value no stricter than 027 (i.e. at least allow\r
+reading and searching by group members).</p>\r
+<p>You can implement finer grained branch policies using update\r
+hooks. There is a document ("control access to branches") in\r
+Documentation/howto by Carl Baldwin and JC outlining how to (1)\r
+limit access to branch per user, (2) forbid overwriting existing\r
+tags.</p>\r
+</div>\r
+<h2>Bundling your work together</h2>\r
+<div class="sectionbody">\r
+<p>It is likely that you will be working on more than one thing at\r
+a time. It is easy to manage those more-or-less independent tasks\r
+using branches with git.</p>\r
+<p>We have already seen how branches work previously,\r
+with "fun and work" example using two branches. The idea is the\r
+same if there are more than two branches. Let's say you started\r
+out from "master" head, and have some new code in the "master"\r
+branch, and two independent fixes in the "commit-fix" and\r
+"diff-fix" branches:</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ git show-branch\r
+! [commit-fix] Fix commit message normalization.\r
+ ! [diff-fix] Fix rename detection.\r
+ * [master] Release candidate #1\r
+---\r
+ + [diff-fix] Fix rename detection.\r
+ + [diff-fix~1] Better common substring algorithm.\r
++ [commit-fix] Fix commit message normalization.\r
+ * [master] Release candidate #1\r
+++* [diff-fix~2] Pretty-print messages.</tt></pre>\r
+</div></div>\r
+<p>Both fixes are tested well, and at this point, you want to merge\r
+in both of them. You could merge in <em>diff-fix</em> first and then\r
+<em>commit-fix</em> next, like this:</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ git merge 'Merge fix in diff-fix' master diff-fix\r
+$ git merge 'Merge fix in commit-fix' master commit-fix</tt></pre>\r
+</div></div>\r
+<p>Which would result in:</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ git show-branch\r
+! [commit-fix] Fix commit message normalization.\r
+ ! [diff-fix] Fix rename detection.\r
+ * [master] Merge fix in commit-fix\r
+---\r
+ - [master] Merge fix in commit-fix\r
++ * [commit-fix] Fix commit message normalization.\r
+ - [master~1] Merge fix in diff-fix\r
+ +* [diff-fix] Fix rename detection.\r
+ +* [diff-fix~1] Better common substring algorithm.\r
+ * [master~2] Release candidate #1\r
+++* [master~3] Pretty-print messages.</tt></pre>\r
+</div></div>\r
+<p>However, there is no particular reason to merge in one branch\r
+first and the other next, when what you have are a set of truly\r
+independent changes (if the order mattered, then they are not\r
+independent by definition). You could instead merge those two\r
+branches into the current branch at once. First let's undo what\r
+we just did and start over. We would want to get the master\r
+branch before these two merges by resetting it to <em>master~2</em>:</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ git reset --hard master~2</tt></pre>\r
+</div></div>\r
+<p>You can make sure <em>git show-branch</em> matches the state before\r
+those two <em>git merge</em> you just did. Then, instead of running\r
+two <em>git merge</em> commands in a row, you would pull these two\r
+branch heads (this is known as <em>making an Octopus</em>):</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ git pull . commit-fix diff-fix\r
+$ git show-branch\r
+! [commit-fix] Fix commit message normalization.\r
+ ! [diff-fix] Fix rename detection.\r
+ * [master] Octopus merge of branches 'diff-fix' and 'commit-fix'\r
+---\r
+ - [master] Octopus merge of branches 'diff-fix' and 'commit-fix'\r
++ * [commit-fix] Fix commit message normalization.\r
+ +* [diff-fix] Fix rename detection.\r
+ +* [diff-fix~1] Better common substring algorithm.\r
+ * [master~1] Release candidate #1\r
+++* [master~2] Pretty-print messages.</tt></pre>\r
+</div></div>\r
+<p>Note that you should not do Octopus because you can. An octopus\r
+is a valid thing to do and often makes it easier to view the\r
+commit history if you are pulling more than two independent\r
+changes at the same time. However, if you have merge conflicts\r
+with any of the branches you are merging in and need to hand\r
+resolve, that is an indication that the development happened in\r
+those branches were not independent after all, and you should\r
+merge two at a time, documenting how you resolved the conflicts,\r
+and the reason why you preferred changes made in one side over\r
+the other. Otherwise it would make the project history harder\r
+to follow, not easier.</p>\r
+</div>\r
+<div id="footer">\r
+<div id="footer-text">\r
+Last updated 22-Jan-2006 23:54:24 PDT\r
+</div>\r
+</div>\r
+</body>\r
+</html>\r
--- /dev/null
+A short git tutorial
+====================
+
+Introduction
+------------
+
+This is trying to be a short tutorial on setting up and using a git
+repository, mainly because being hands-on and using explicit examples is
+often the best way of explaining what is going on.
+
+In normal life, most people wouldn't use the "core" git programs
+directly, but rather script around them to make them more palatable.
+Understanding the core git stuff may help some people get those scripts
+done, though, and it may also be instructive in helping people
+understand what it is that the higher-level helper scripts are actually
+doing.
+
+The core git is often called "plumbing", with the prettier user
+interfaces on top of it called "porcelain". You may not want to use the
+plumbing directly very often, but it can be good to know what the
+plumbing does for when the porcelain isn't flushing.
+
+The material presented here often goes deep describing how things
+work internally. If you are mostly interested in using git as a
+SCM, you can skip them during your first pass.
+
+[NOTE]
+And those "too deep" descriptions are often marked as Note.
+
+[NOTE]
+If you are already familiar with another version control system,
+like CVS, you may want to take a look at
+link:everyday.html[Everyday GIT in 20 commands or so] first
+before reading this.
+
+
+Creating a git repository
+-------------------------
+
+Creating a new git repository couldn't be easier: all git repositories start
+out empty, and the only thing you need to do is find yourself a
+subdirectory that you want to use as a working tree - either an empty
+one for a totally new project, or an existing working tree that you want
+to import into git.
+
+For our first example, we're going to start a totally new repository from
+scratch, with no pre-existing files, and we'll call it `git-tutorial`.
+To start up, create a subdirectory for it, change into that
+subdirectory, and initialize the git infrastructure with `git-init-db`:
+
+------------------------------------------------
+$ mkdir git-tutorial
+$ cd git-tutorial
+$ git-init-db
+------------------------------------------------
+
+to which git will reply
+
+----------------
+defaulting to local storage area
+----------------
+
+which is just git's way of saying that you haven't been doing anything
+strange, and that it will have created a local `.git` directory setup for
+your new project. You will now have a `.git` directory, and you can
+inspect that with `ls`. For your new empty project, it should show you
+three entries, among other things:
+
+ - a symlink called `HEAD`, pointing to `refs/heads/master` (if your
+ platform does not have native symlinks, it is a file containing the
+ line "ref: refs/heads/master")
++
+Don't worry about the fact that the file that the `HEAD` link points to
+doesn't even exist yet -- you haven't created the commit that will
+start your `HEAD` development branch yet.
+
+ - a subdirectory called `objects`, which will contain all the
+ objects of your project. You should never have any real reason to
+ look at the objects directly, but you might want to know that these
+ objects are what contains all the real 'data' in your repository.
+
+ - a subdirectory called `refs`, which contains references to objects.
+
+In particular, the `refs` subdirectory will contain two other
+subdirectories, named `heads` and `tags` respectively. They do
+exactly what their names imply: they contain references to any number
+of different 'heads' of development (aka 'branches'), and to any
+'tags' that you have created to name specific versions in your
+repository.
+
+One note: the special `master` head is the default branch, which is
+why the `.git/HEAD` file was created as a symlink to it even if it
+doesn't yet exist. Basically, the `HEAD` link is supposed to always
+point to the branch you are working on right now, and you always
+start out expecting to work on the `master` branch.
+
+However, this is only a convention, and you can name your branches
+anything you want, and don't have to ever even 'have' a `master`
+branch. A number of the git tools will assume that `.git/HEAD` is
+valid, though.
+
+[NOTE]
+An 'object' is identified by its 160-bit SHA1 hash, aka 'object name',
+and a reference to an object is always the 40-byte hex
+representation of that SHA1 name. The files in the `refs`
+subdirectory are expected to contain these hex references
+(usually with a final `\'\n\'` at the end), and you should thus
+expect to see a number of 41-byte files containing these
+references in these `refs` subdirectories when you actually start
+populating your tree.
+
+[NOTE]
+An advanced user may want to take a look at the
+link:repository-layout.html[repository layout] document
+after finishing this tutorial.
+
+You have now created your first git repository. Of course, since it's
+empty, that's not very useful, so let's start populating it with data.
+
+
+Populating a git repository
+---------------------------
+
+We'll keep this simple and stupid, so we'll start off with populating a
+few trivial files just to get a feel for it.
+
+Start off with just creating any random files that you want to maintain
+in your git repository. We'll start off with a few bad examples, just to
+get a feel for how this works:
+
+------------------------------------------------
+$ echo "Hello World" >hello
+$ echo "Silly example" >example
+------------------------------------------------
+
+you have now created two files in your working tree (aka 'working directory'), but to
+actually check in your hard work, you will have to go through two steps:
+
+ - fill in the 'index' file (aka 'cache') with the information about your
+ working tree state.
+
+ - commit that index file as an object.
+
+The first step is trivial: when you want to tell git about any changes
+to your working tree, you use the `git-update-index` program. That
+program normally just takes a list of filenames you want to update, but
+to avoid trivial mistakes, it refuses to add new entries to the index
+(or remove existing ones) unless you explicitly tell it that you're
+adding a new entry with the `\--add` flag (or removing an entry with the
+`\--remove`) flag.
+
+So to populate the index with the two files you just created, you can do
+
+------------------------------------------------
+$ git-update-index --add hello example
+------------------------------------------------
+
+and you have now told git to track those two files.
+
+In fact, as you did that, if you now look into your object directory,
+you'll notice that git will have added two new objects to the object
+database. If you did exactly the steps above, you should now be able to do
+
+
+----------------
+$ ls .git/objects/??/*
+----------------
+
+and see two files:
+
+----------------
+.git/objects/55/7db03de997c86a4a028e1ebd3a1ceb225be238
+.git/objects/f2/4c74a2e500f5ee1332c86b94199f52b1d1d962
+----------------
+
+which correspond with the objects with names of 557db... and f24c7..
+respectively.
+
+If you want to, you can use `git-cat-file` to look at those objects, but
+you'll have to use the object name, not the filename of the object:
+
+----------------
+$ git-cat-file -t 557db03de997c86a4a028e1ebd3a1ceb225be238
+----------------
+
+where the `-t` tells `git-cat-file` to tell you what the "type" of the
+object is. git will tell you that you have a "blob" object (ie just a
+regular file), and you can see the contents with
+
+----------------
+$ git-cat-file "blob" 557db03
+----------------
+
+which will print out "Hello World". The object 557db03 is nothing
+more than the contents of your file `hello`.
+
+[NOTE]
+Don't confuse that object with the file `hello` itself. The
+object is literally just those specific *contents* of the file, and
+however much you later change the contents in file `hello`, the object
+we just looked at will never change. Objects are immutable.
+
+[NOTE]
+The second example demonstrates that you can
+abbreviate the object name to only the first several
+hexadecimal digits in most places.
+
+Anyway, as we mentioned previously, you normally never actually take a
+look at the objects themselves, and typing long 40-character hex
+names is not something you'd normally want to do. The above digression
+was just to show that `git-update-index` did something magical, and
+actually saved away the contents of your files into the git object
+database.
+
+Updating the index did something else too: it created a `.git/index`
+file. This is the index that describes your current working tree, and
+something you should be very aware of. Again, you normally never worry
+about the index file itself, but you should be aware of the fact that
+you have not actually really "checked in" your files into git so far,
+you've only *told* git about them.
+
+However, since git knows about them, you can now start using some of the
+most basic git commands to manipulate the files or look at their status.
+
+In particular, let's not even check in the two files into git yet, we'll
+start off by adding another line to `hello` first:
+
+------------------------------------------------
+$ echo "It's a new day for git" >>hello
+------------------------------------------------
+
+and you can now, since you told git about the previous state of `hello`, ask
+git what has changed in the tree compared to your old index, using the
+`git-diff-files` command:
+
+------------
+$ git-diff-files
+------------
+
+Oops. That wasn't very readable. It just spit out its own internal
+version of a `diff`, but that internal version really just tells you
+that it has noticed that "hello" has been modified, and that the old object
+contents it had have been replaced with something else.
+
+To make it readable, we can tell git-diff-files to output the
+differences as a patch, using the `-p` flag:
+
+------------
+$ git-diff-files -p
+diff --git a/hello b/hello
+index 557db03..263414f 100644
+--- a/hello
++++ b/hello
+@@ -1 +1,2 @@
+ Hello World
++It's a new day for git
+----
+
+i.e. the diff of the change we caused by adding another line to `hello`.
+
+In other words, `git-diff-files` always shows us the difference between
+what is recorded in the index, and what is currently in the working
+tree. That's very useful.
+
+A common shorthand for `git-diff-files -p` is to just write `git
+diff`, which will do the same thing.
+
+------------
+$ git diff
+diff --git a/hello b/hello
+index 557db03..263414f 100644
+--- a/hello
++++ b/hello
+@@ -1 +1,2 @@
+ Hello World
++It's a new day for git
+------------
+
+
+Committing git state
+--------------------
+
+Now, we want to go to the next stage in git, which is to take the files
+that git knows about in the index, and commit them as a real tree. We do
+that in two phases: creating a 'tree' object, and committing that 'tree'
+object as a 'commit' object together with an explanation of what the
+tree was all about, along with information of how we came to that state.
+
+Creating a tree object is trivial, and is done with `git-write-tree`.
+There are no options or other input: git-write-tree will take the
+current index state, and write an object that describes that whole
+index. In other words, we're now tying together all the different
+filenames with their contents (and their permissions), and we're
+creating the equivalent of a git "directory" object:
+
+------------------------------------------------
+$ git-write-tree
+------------------------------------------------
+
+and this will just output the name of the resulting tree, in this case
+(if you have done exactly as I've described) it should be
+
+----------------
+8988da15d077d4829fc51d8544c097def6644dbb
+----------------
+
+which is another incomprehensible object name. Again, if you want to,
+you can use `git-cat-file -t 8988d\...` to see that this time the object
+is not a "blob" object, but a "tree" object (you can also use
+`git-cat-file` to actually output the raw object contents, but you'll see
+mainly a binary mess, so that's less interesting).
+
+However -- normally you'd never use `git-write-tree` on its own, because
+normally you always commit a tree into a commit object using the
+`git-commit-tree` command. In fact, it's easier to not actually use
+`git-write-tree` on its own at all, but to just pass its result in as an
+argument to `git-commit-tree`.
+
+`git-commit-tree` normally takes several arguments -- it wants to know
+what the 'parent' of a commit was, but since this is the first commit
+ever in this new repository, and it has no parents, we only need to pass in
+the object name of the tree. However, `git-commit-tree`
+also wants to get a commit message
+on its standard input, and it will write out the resulting object name for the
+commit to its standard output.
+
+And this is where we create the `.git/refs/heads/master` file
+which is pointed at by `HEAD`. This file is supposed to contain
+the reference to the top-of-tree of the master branch, and since
+that's exactly what `git-commit-tree` spits out, we can do this
+all with a sequence of simple shell commands:
+
+------------------------------------------------
+$ tree=$(git-write-tree)
+$ commit=$(echo 'Initial commit' | git-commit-tree $tree)
+$ git-update-ref HEAD $commit
+------------------------------------------------
+
+which will say:
+
+----------------
+Committing initial tree 8988da15d077d4829fc51d8544c097def6644dbb
+----------------
+
+just to warn you about the fact that it created a totally new commit
+that is not related to anything else. Normally you do this only *once*
+for a project ever, and all later commits will be parented on top of an
+earlier commit, and you'll never see this "Committing initial tree"
+message ever again.
+
+Again, normally you'd never actually do this by hand. There is a
+helpful script called `git commit` that will do all of this for you. So
+you could have just written `git commit`
+instead, and it would have done the above magic scripting for you.
+
+
+Making a change
+---------------
+
+Remember how we did the `git-update-index` on file `hello` and then we
+changed `hello` afterward, and could compare the new state of `hello` with the
+state we saved in the index file?
+
+Further, remember how I said that `git-write-tree` writes the contents
+of the *index* file to the tree, and thus what we just committed was in
+fact the *original* contents of the file `hello`, not the new ones. We did
+that on purpose, to show the difference between the index state, and the
+state in the working tree, and how they don't have to match, even
+when we commit things.
+
+As before, if we do `git-diff-files -p` in our git-tutorial project,
+we'll still see the same difference we saw last time: the index file
+hasn't changed by the act of committing anything. However, now that we
+have committed something, we can also learn to use a new command:
+`git-diff-index`.
+
+Unlike `git-diff-files`, which showed the difference between the index
+file and the working tree, `git-diff-index` shows the differences
+between a committed *tree* and either the index file or the working
+tree. In other words, `git-diff-index` wants a tree to be diffed
+against, and before we did the commit, we couldn't do that, because we
+didn't have anything to diff against.
+
+But now we can do
+
+----------------
+$ git-diff-index -p HEAD
+----------------
+
+(where `-p` has the same meaning as it did in `git-diff-files`), and it
+will show us the same difference, but for a totally different reason.
+Now we're comparing the working tree not against the index file,
+but against the tree we just wrote. It just so happens that those two
+are obviously the same, so we get the same result.
+
+Again, because this is a common operation, you can also just shorthand
+it with
+
+----------------
+$ git diff HEAD
+----------------
+
+which ends up doing the above for you.
+
+In other words, `git-diff-index` normally compares a tree against the
+working tree, but when given the `\--cached` flag, it is told to
+instead compare against just the index cache contents, and ignore the
+current working tree state entirely. Since we just wrote the index
+file to HEAD, doing `git-diff-index \--cached -p HEAD` should thus return
+an empty set of differences, and that's exactly what it does.
+
+[NOTE]
+================
+`git-diff-index` really always uses the index for its
+comparisons, and saying that it compares a tree against the working
+tree is thus not strictly accurate. In particular, the list of
+files to compare (the "meta-data") *always* comes from the index file,
+regardless of whether the `\--cached` flag is used or not. The `\--cached`
+flag really only determines whether the file *contents* to be compared
+come from the working tree or not.
+
+This is not hard to understand, as soon as you realize that git simply
+never knows (or cares) about files that it is not told about
+explicitly. git will never go *looking* for files to compare, it
+expects you to tell it what the files are, and that's what the index
+is there for.
+================
+
+However, our next step is to commit the *change* we did, and again, to
+understand what's going on, keep in mind the difference between "working
+tree contents", "index file" and "committed tree". We have changes
+in the working tree that we want to commit, and we always have to
+work through the index file, so the first thing we need to do is to
+update the index cache:
+
+------------------------------------------------
+$ git-update-index hello
+------------------------------------------------
+
+(note how we didn't need the `\--add` flag this time, since git knew
+about the file already).
+
+Note what happens to the different `git-diff-\*` versions here. After
+we've updated `hello` in the index, `git-diff-files -p` now shows no
+differences, but `git-diff-index -p HEAD` still *does* show that the
+current state is different from the state we committed. In fact, now
+`git-diff-index` shows the same difference whether we use the `--cached`
+flag or not, since now the index is coherent with the working tree.
+
+Now, since we've updated `hello` in the index, we can commit the new
+version. We could do it by writing the tree by hand again, and
+committing the tree (this time we'd have to use the `-p HEAD` flag to
+tell commit that the HEAD was the *parent* of the new commit, and that
+this wasn't an initial commit any more), but you've done that once
+already, so let's just use the helpful script this time:
+
+------------------------------------------------
+$ git commit
+------------------------------------------------
+
+which starts an editor for you to write the commit message and tells you
+a bit about what you have done.
+
+Write whatever message you want, and all the lines that start with '#'
+will be pruned out, and the rest will be used as the commit message for
+the change. If you decide you don't want to commit anything after all at
+this point (you can continue to edit things and update the index), you
+can just leave an empty message. Otherwise `git commit` will commit
+the change for you.
+
+You've now made your first real git commit. And if you're interested in
+looking at what `git commit` really does, feel free to investigate:
+it's a few very simple shell scripts to generate the helpful (?) commit
+message headers, and a few one-liners that actually do the
+commit itself (`git-commit`).
+
+
+Inspecting Changes
+------------------
+
+While creating changes is useful, it's even more useful if you can tell
+later what changed. The most useful command for this is another of the
+`diff` family, namely `git-diff-tree`.
+
+`git-diff-tree` can be given two arbitrary trees, and it will tell you the
+differences between them. Perhaps even more commonly, though, you can
+give it just a single commit object, and it will figure out the parent
+of that commit itself, and show the difference directly. Thus, to get
+the same diff that we've already seen several times, we can now do
+
+----------------
+$ git-diff-tree -p HEAD
+----------------
+
+(again, `-p` means to show the difference as a human-readable patch),
+and it will show what the last commit (in `HEAD`) actually changed.
+
+[NOTE]
+============
+Here is an ASCII art by Jon Loeliger that illustrates how
+various diff-\* commands compare things.
+
+ diff-tree
+ +----+
+ | |
+ | |
+ V V
+ +-----------+
+ | Object DB |
+ | Backing |
+ | Store |
+ +-----------+
+ ^ ^
+ | |
+ | | diff-index --cached
+ | |
+ diff-index | V
+ | +-----------+
+ | | Index |
+ | | "cache" |
+ | +-----------+
+ | ^
+ | |
+ | | diff-files
+ | |
+ V V
+ +-----------+
+ | Working |
+ | Directory |
+ +-----------+
+============
+
+More interestingly, you can also give `git-diff-tree` the `-v` flag, which
+tells it to also show the commit message and author and date of the
+commit, and you can tell it to show a whole series of diffs.
+Alternatively, you can tell it to be "silent", and not show the diffs at
+all, but just show the actual commit message.
+
+In fact, together with the `git-rev-list` program (which generates a
+list of revisions), `git-diff-tree` ends up being a veritable fount of
+changes. A trivial (but very useful) script called `git-whatchanged` is
+included with git which does exactly this, and shows a log of recent
+activities.
+
+To see the whole history of our pitiful little git-tutorial project, you
+can do
+
+----------------
+$ git log
+----------------
+
+which shows just the log messages, or if we want to see the log together
+with the associated patches use the more complex (and much more
+powerful)
+
+----------------
+$ git-whatchanged -p --root
+----------------
+
+and you will see exactly what has changed in the repository over its
+short history.
+
+[NOTE]
+The `\--root` flag is a flag to `git-diff-tree` to tell it to
+show the initial aka 'root' commit too. Normally you'd probably not
+want to see the initial import diff, but since the tutorial project
+was started from scratch and is so small, we use it to make the result
+a bit more interesting.
+
+With that, you should now be having some inkling of what git does, and
+can explore on your own.
+
+[NOTE]
+Most likely, you are not directly using the core
+git Plumbing commands, but using Porcelain like Cogito on top
+of it. Cogito works a bit differently and you usually do not
+have to run `git-update-index` yourself for changed files (you
+do tell underlying git about additions and removals via
+`cg-add` and `cg-rm` commands). Just before you make a commit
+with `cg-commit`, Cogito figures out which files you modified,
+and runs `git-update-index` on them for you.
+
+
+Tagging a version
+-----------------
+
+In git, there are two kinds of tags, a "light" one, and an "annotated tag".
+
+A "light" tag is technically nothing more than a branch, except we put
+it in the `.git/refs/tags/` subdirectory instead of calling it a `head`.
+So the simplest form of tag involves nothing more than
+
+------------------------------------------------
+$ git tag my-first-tag
+------------------------------------------------
+
+which just writes the current `HEAD` into the `.git/refs/tags/my-first-tag`
+file, after which point you can then use this symbolic name for that
+particular state. You can, for example, do
+
+----------------
+$ git diff my-first-tag
+----------------
+
+to diff your current state against that tag (which at this point will
+obviously be an empty diff, but if you continue to develop and commit
+stuff, you can use your tag as an "anchor-point" to see what has changed
+since you tagged it.
+
+An "annotated tag" is actually a real git object, and contains not only a
+pointer to the state you want to tag, but also a small tag name and
+message, along with optionally a PGP signature that says that yes,
+you really did
+that tag. You create these annotated tags with either the `-a` or
+`-s` flag to `git tag`:
+
+----------------
+$ git tag -s <tagname>
+----------------
+
+which will sign the current `HEAD` (but you can also give it another
+argument that specifies the thing to tag, ie you could have tagged the
+current `mybranch` point by using `git tag <tagname> mybranch`).
+
+You normally only do signed tags for major releases or things
+like that, while the light-weight tags are useful for any marking you
+want to do -- any time you decide that you want to remember a certain
+point, just create a private tag for it, and you have a nice symbolic
+name for the state at that point.
+
+
+Copying repositories
+--------------------
+
+git repositories are normally totally self-sufficient and relocatable
+Unlike CVS, for example, there is no separate notion of
+"repository" and "working tree". A git repository normally *is* the
+working tree, with the local git information hidden in the `.git`
+subdirectory. There is nothing else. What you see is what you got.
+
+[NOTE]
+You can tell git to split the git internal information from
+the directory that it tracks, but we'll ignore that for now: it's not
+how normal projects work, and it's really only meant for special uses.
+So the mental model of "the git information is always tied directly to
+the working tree that it describes" may not be technically 100%
+accurate, but it's a good model for all normal use.
+
+This has two implications:
+
+ - if you grow bored with the tutorial repository you created (or you've
+ made a mistake and want to start all over), you can just do simple
++
+----------------
+$ rm -rf git-tutorial
+----------------
++
+and it will be gone. There's no external repository, and there's no
+history outside the project you created.
+
+ - if you want to move or duplicate a git repository, you can do so. There
+ is `git clone` command, but if all you want to do is just to
+ create a copy of your repository (with all the full history that
+ went along with it), you can do so with a regular
+ `cp -a git-tutorial new-git-tutorial`.
++
+Note that when you've moved or copied a git repository, your git index
+file (which caches various information, notably some of the "stat"
+information for the files involved) will likely need to be refreshed.
+So after you do a `cp -a` to create a new copy, you'll want to do
++
+----------------
+$ git-update-index --refresh
+----------------
++
+in the new repository to make sure that the index file is up-to-date.
+
+Note that the second point is true even across machines. You can
+duplicate a remote git repository with *any* regular copy mechanism, be it
+`scp`, `rsync` or `wget`.
+
+When copying a remote repository, you'll want to at a minimum update the
+index cache when you do this, and especially with other peoples'
+repositories you often want to make sure that the index cache is in some
+known state (you don't know *what* they've done and not yet checked in),
+so usually you'll precede the `git-update-index` with a
+
+----------------
+$ git-read-tree --reset HEAD
+$ git-update-index --refresh
+----------------
+
+which will force a total index re-build from the tree pointed to by `HEAD`.
+It resets the index contents to `HEAD`, and then the `git-update-index`
+makes sure to match up all index entries with the checked-out files.
+If the original repository had uncommitted changes in its
+working tree, `git-update-index --refresh` notices them and
+tells you they need to be updated.
+
+The above can also be written as simply
+
+----------------
+$ git reset
+----------------
+
+and in fact a lot of the common git command combinations can be scripted
+with the `git xyz` interfaces. You can learn things by just looking
+at what the various git scripts do. For example, `git reset` is the
+above two lines implemented in `git-reset`, but some things like
+`git status` and `git commit` are slightly more complex scripts around
+the basic git commands.
+
+Many (most?) public remote repositories will not contain any of
+the checked out files or even an index file, and will *only* contain the
+actual core git files. Such a repository usually doesn't even have the
+`.git` subdirectory, but has all the git files directly in the
+repository.
+
+To create your own local live copy of such a "raw" git repository, you'd
+first create your own subdirectory for the project, and then copy the
+raw repository contents into the `.git` directory. For example, to
+create your own copy of the git repository, you'd do the following
+
+----------------
+$ mkdir my-git
+$ cd my-git
+$ rsync -rL rsync://rsync.kernel.org/pub/scm/git/git.git/ .git
+----------------
+
+followed by
+
+----------------
+$ git-read-tree HEAD
+----------------
+
+to populate the index. However, now you have populated the index, and
+you have all the git internal files, but you will notice that you don't
+actually have any of the working tree files to work on. To get
+those, you'd check them out with
+
+----------------
+$ git-checkout-index -u -a
+----------------
+
+where the `-u` flag means that you want the checkout to keep the index
+up-to-date (so that you don't have to refresh it afterward), and the
+`-a` flag means "check out all files" (if you have a stale copy or an
+older version of a checked out tree you may also need to add the `-f`
+flag first, to tell git-checkout-index to *force* overwriting of any old
+files).
+
+Again, this can all be simplified with
+
+----------------
+$ git clone rsync://rsync.kernel.org/pub/scm/git/git.git/ my-git
+$ cd my-git
+$ git checkout
+----------------
+
+which will end up doing all of the above for you.
+
+You have now successfully copied somebody else's (mine) remote
+repository, and checked it out.
+
+
+Creating a new branch
+---------------------
+
+Branches in git are really nothing more than pointers into the git
+object database from within the `.git/refs/` subdirectory, and as we
+already discussed, the `HEAD` branch is nothing but a symlink to one of
+these object pointers.
+
+You can at any time create a new branch by just picking an arbitrary
+point in the project history, and just writing the SHA1 name of that
+object into a file under `.git/refs/heads/`. You can use any filename you
+want (and indeed, subdirectories), but the convention is that the
+"normal" branch is called `master`. That's just a convention, though,
+and nothing enforces it.
+
+To show that as an example, let's go back to the git-tutorial repository we
+used earlier, and create a branch in it. You do that by simply just
+saying that you want to check out a new branch:
+
+------------
+$ git checkout -b mybranch
+------------
+
+will create a new branch based at the current `HEAD` position, and switch
+to it.
+
+[NOTE]
+================================================
+If you make the decision to start your new branch at some
+other point in the history than the current `HEAD`, you can do so by
+just telling `git checkout` what the base of the checkout would be.
+In other words, if you have an earlier tag or branch, you'd just do
+
+------------
+$ git checkout -b mybranch earlier-commit
+------------
+
+and it would create the new branch `mybranch` at the earlier commit,
+and check out the state at that time.
+================================================
+
+You can always just jump back to your original `master` branch by doing
+
+------------
+$ git checkout master
+------------
+
+(or any other branch-name, for that matter) and if you forget which
+branch you happen to be on, a simple
+
+------------
+$ ls -l .git/HEAD
+------------
+
+will tell you where it's pointing (Note that on platforms with bad or no
+symlink support, you have to execute
+
+------------
+$ cat .git/HEAD
+------------
+
+instead). To get the list of branches you have, you can say
+
+------------
+$ git branch
+------------
+
+which is nothing more than a simple script around `ls .git/refs/heads`.
+There will be asterisk in front of the branch you are currently on.
+
+Sometimes you may wish to create a new branch _without_ actually
+checking it out and switching to it. If so, just use the command
+
+------------
+$ git branch <branchname> [startingpoint]
+------------
+
+which will simply _create_ the branch, but will not do anything further.
+You can then later -- once you decide that you want to actually develop
+on that branch -- switch to that branch with a regular `git checkout`
+with the branchname as the argument.
+
+
+Merging two branches
+--------------------
+
+One of the ideas of having a branch is that you do some (possibly
+experimental) work in it, and eventually merge it back to the main
+branch. So assuming you created the above `mybranch` that started out
+being the same as the original `master` branch, let's make sure we're in
+that branch, and do some work there.
+
+------------------------------------------------
+$ git checkout mybranch
+$ echo "Work, work, work" >>hello
+$ git commit -m 'Some work.' hello
+------------------------------------------------
+
+Here, we just added another line to `hello`, and we used a shorthand for
+doing both `git-update-index hello` and `git commit` by just giving the
+filename directly to `git commit`. The `-m` flag is to give the
+commit log message from the command line.
+
+Now, to make it a bit more interesting, let's assume that somebody else
+does some work in the original branch, and simulate that by going back
+to the master branch, and editing the same file differently there:
+
+------------
+$ git checkout master
+------------
+
+Here, take a moment to look at the contents of `hello`, and notice how they
+don't contain the work we just did in `mybranch` -- because that work
+hasn't happened in the `master` branch at all. Then do
+
+------------
+$ echo "Play, play, play" >>hello
+$ echo "Lots of fun" >>example
+$ git commit -m 'Some fun.' hello example
+------------
+
+since the master branch is obviously in a much better mood.
+
+Now, you've got two branches, and you decide that you want to merge the
+work done. Before we do that, let's introduce a cool graphical tool that
+helps you view what's going on:
+
+----------------
+$ gitk --all
+----------------
+
+will show you graphically both of your branches (that's what the `\--all`
+means: normally it will just show you your current `HEAD`) and their
+histories. You can also see exactly how they came to be from a common
+source.
+
+Anyway, let's exit `gitk` (`^Q` or the File menu), and decide that we want
+to merge the work we did on the `mybranch` branch into the `master`
+branch (which is currently our `HEAD` too). To do that, there's a nice
+script called `git merge`, which wants to know which branches you want
+to resolve and what the merge is all about:
+
+------------
+$ git merge "Merge work in mybranch" HEAD mybranch
+------------
+
+where the first argument is going to be used as the commit message if
+the merge can be resolved automatically.
+
+Now, in this case we've intentionally created a situation where the
+merge will need to be fixed up by hand, though, so git will do as much
+of it as it can automatically (which in this case is just merge the `example`
+file, which had no differences in the `mybranch` branch), and say:
+
+----------------
+ Trying really trivial in-index merge...
+ fatal: Merge requires file-level merging
+ Nope.
+ ...
+ Auto-merging hello
+ CONFLICT (content): Merge conflict in hello
+ Automatic merge failed/prevented; fix up by hand
+----------------
+
+which is way too verbose, but it basically tells you that it failed the
+really trivial merge ("Simple merge") and did an "Automatic merge"
+instead, but that too failed due to conflicts in `hello`.
+
+Not to worry. It left the (trivial) conflict in `hello` in the same form you
+should already be well used to if you've ever used CVS, so let's just
+open `hello` in our editor (whatever that may be), and fix it up somehow.
+I'd suggest just making it so that `hello` contains all four lines:
+
+------------
+Hello World
+It's a new day for git
+Play, play, play
+Work, work, work
+------------
+
+and once you're happy with your manual merge, just do a
+
+------------
+$ git commit hello
+------------
+
+which will very loudly warn you that you're now committing a merge
+(which is correct, so never mind), and you can write a small merge
+message about your adventures in git-merge-land.
+
+After you're done, start up `gitk \--all` to see graphically what the
+history looks like. Notice that `mybranch` still exists, and you can
+switch to it, and continue to work with it if you want to. The
+`mybranch` branch will not contain the merge, but next time you merge it
+from the `master` branch, git will know how you merged it, so you'll not
+have to do _that_ merge again.
+
+Another useful tool, especially if you do not always work in X-Window
+environment, is `git show-branch`.
+
+------------------------------------------------
+$ git show-branch master mybranch
+* [master] Merge work in mybranch
+ ! [mybranch] Some work.
+--
+- [master] Merge work in mybranch
+*+ [mybranch] Some work.
+------------------------------------------------
+
+The first two lines indicate that it is showing the two branches
+and the first line of the commit log message from their
+top-of-the-tree commits, you are currently on `master` branch
+(notice the asterisk `*` character), and the first column for
+the later output lines is used to show commits contained in the
+`master` branch, and the second column for the `mybranch`
+branch. Three commits are shown along with their log messages.
+All of them have non blank characters in the first column (`*`
+shows an ordinary commit on the current branch, `.` is a merge commit), which
+means they are now part of the `master` branch. Only the "Some
+work" commit has the plus `+` character in the second column,
+because `mybranch` has not been merged to incorporate these
+commits from the master branch. The string inside brackets
+before the commit log message is a short name you can use to
+name the commit. In the above example, 'master' and 'mybranch'
+are branch heads. 'master~1' is the first parent of 'master'
+branch head. Please see 'git-rev-parse' documentation if you
+see more complex cases.
+
+Now, let's pretend you are the one who did all the work in
+`mybranch`, and the fruit of your hard work has finally been merged
+to the `master` branch. Let's go back to `mybranch`, and run
+resolve to get the "upstream changes" back to your branch.
+
+------------
+$ git checkout mybranch
+$ git merge "Merge upstream changes." HEAD master
+------------
+
+This outputs something like this (the actual commit object names
+would be different)
+
+----------------
+Updating from ae3a2da... to a80b4aa....
+ example | 1 +
+ hello | 1 +
+ 2 files changed, 2 insertions(+), 0 deletions(-)
+----------------
+
+Because your branch did not contain anything more than what are
+already merged into the `master` branch, the resolve operation did
+not actually do a merge. Instead, it just updated the top of
+the tree of your branch to that of the `master` branch. This is
+often called 'fast forward' merge.
+
+You can run `gitk \--all` again to see how the commit ancestry
+looks like, or run `show-branch`, which tells you this.
+
+------------------------------------------------
+$ git show-branch master mybranch
+! [master] Merge work in mybranch
+ * [mybranch] Merge work in mybranch
+--
+-- [master] Merge work in mybranch
+------------------------------------------------
+
+
+Merging external work
+---------------------
+
+It's usually much more common that you merge with somebody else than
+merging with your own branches, so it's worth pointing out that git
+makes that very easy too, and in fact, it's not that different from
+doing a `git merge`. In fact, a remote merge ends up being nothing
+more than "fetch the work from a remote repository into a temporary tag"
+followed by a `git merge`.
+
+Fetching from a remote repository is done by, unsurprisingly,
+`git fetch`:
+
+----------------
+$ git fetch <remote-repository>
+----------------
+
+One of the following transports can be used to name the
+repository to download from:
+
+Rsync::
+ `rsync://remote.machine/path/to/repo.git/`
++
+Rsync transport is usable for both uploading and downloading,
+but is completely unaware of what git does, and can produce
+unexpected results when you download from the public repository
+while the repository owner is uploading into it via `rsync`
+transport. Most notably, it could update the files under
+`refs/` which holds the object name of the topmost commits
+before uploading the files in `objects/` -- the downloader would
+obtain head commit object name while that object itself is still
+not available in the repository. For this reason, it is
+considered deprecated.
+
+SSH::
+ `remote.machine:/path/to/repo.git/` or
++
+`ssh://remote.machine/path/to/repo.git/`
++
+This transport can be used for both uploading and downloading,
+and requires you to have a log-in privilege over `ssh` to the
+remote machine. It finds out the set of objects the other side
+lacks by exchanging the head commits both ends have and
+transfers (close to) minimum set of objects. It is by far the
+most efficient way to exchange git objects between repositories.
+
+Local directory::
+ `/path/to/repo.git/`
++
+This transport is the same as SSH transport but uses `sh` to run
+both ends on the local machine instead of running other end on
+the remote machine via `ssh`.
+
+git Native::
+ `git://remote.machine/path/to/repo.git/`
++
+This transport was designed for anonymous downloading. Like SSH
+transport, it finds out the set of objects the downstream side
+lacks and transfers (close to) minimum set of objects.
+
+HTTP(S)::
+ `http://remote.machine/path/to/repo.git/`
++
+Downloader from http and https URL
+first obtains the topmost commit object name from the remote site
+by looking at the specified refname under `repo.git/refs/` directory,
+and then tries to obtain the
+commit object by downloading from `repo.git/objects/xx/xxx\...`
+using the object name of that commit object. Then it reads the
+commit object to find out its parent commits and the associate
+tree object; it repeats this process until it gets all the
+necessary objects. Because of this behaviour, they are
+sometimes also called 'commit walkers'.
++
+The 'commit walkers' are sometimes also called 'dumb
+transports', because they do not require any git aware smart
+server like git Native transport does. Any stock HTTP server
+that does not even support directory index would suffice. But
+you must prepare your repository with `git-update-server-info`
+to help dumb transport downloaders.
++
+There are (confusingly enough) `git-ssh-fetch` and `git-ssh-upload`
+programs, which are 'commit walkers'; they outlived their
+usefulness when git Native and SSH transports were introduced,
+and not used by `git pull` or `git push` scripts.
+
+Once you fetch from the remote repository, you `resolve` that
+with your current branch.
+
+However -- it's such a common thing to `fetch` and then
+immediately `resolve`, that it's called `git pull`, and you can
+simply do
+
+----------------
+$ git pull <remote-repository>
+----------------
+
+and optionally give a branch-name for the remote end as a second
+argument.
+
+[NOTE]
+You could do without using any branches at all, by
+keeping as many local repositories as you would like to have
+branches, and merging between them with `git pull`, just like
+you merge between branches. The advantage of this approach is
+that it lets you keep set of files for each `branch` checked
+out and you may find it easier to switch back and forth if you
+juggle multiple lines of development simultaneously. Of
+course, you will pay the price of more disk usage to hold
+multiple working trees, but disk space is cheap these days.
+
+[NOTE]
+You could even pull from your own repository by
+giving '.' as <remote-repository> parameter to `git pull`. This
+is useful when you want to merge a local branch (or more, if you
+are making an Octopus) into the current branch.
+
+It is likely that you will be pulling from the same remote
+repository from time to time. As a short hand, you can store
+the remote repository URL in a file under .git/remotes/
+directory, like this:
+
+------------------------------------------------
+$ mkdir -p .git/remotes/
+$ cat >.git/remotes/linus <<\EOF
+URL: http://www.kernel.org/pub/scm/git/git.git/
+EOF
+------------------------------------------------
+
+and use the filename to `git pull` instead of the full URL.
+The URL specified in such file can even be a prefix
+of a full URL, like this:
+
+------------------------------------------------
+$ cat >.git/remotes/jgarzik <<\EOF
+URL: http://www.kernel.org/pub/scm/linux/git/jgarzik/
+EOF
+------------------------------------------------
+
+
+Examples.
+
+. `git pull linus`
+. `git pull linus tag v0.99.1`
+. `git pull jgarzik/netdev-2.6.git/ e100`
+
+the above are equivalent to:
+
+. `git pull http://www.kernel.org/pub/scm/git/git.git/ HEAD`
+. `git pull http://www.kernel.org/pub/scm/git/git.git/ tag v0.99.1`
+. `git pull http://www.kernel.org/pub/.../jgarzik/netdev-2.6.git e100`
+
+
+How does the merge work?
+------------------------
+
+We said this tutorial shows what plumbing does to help you cope
+with the porcelain that isn't flushing, but we so far did not
+talk about how the merge really works. If you are following
+this tutorial the first time, I'd suggest to skip to "Publishing
+your work" section and come back here later.
+
+OK, still with me? To give us an example to look at, let's go
+back to the earlier repository with "hello" and "example" file,
+and bring ourselves back to the pre-merge state:
+
+------------
+$ git show-branch --more=3 master mybranch
+! [master] Merge work in mybranch
+ * [mybranch] Merge work in mybranch
+--
+-- [master] Merge work in mybranch
++* [master^2] Some work.
++* [master^] Some fun.
+------------
+
+Remember, before running `git merge`, our `master` head was at
+"Some fun." commit, while our `mybranch` head was at "Some
+work." commit.
+
+------------
+$ git checkout mybranch
+$ git reset --hard master^2
+$ git checkout master
+$ git reset --hard master^
+------------
+
+After rewinding, the commit structure should look like this:
+
+------------
+$ git show-branch
+* [master] Some fun.
+ ! [mybranch] Some work.
+--
+ + [mybranch] Some work.
+* [master] Some fun.
+*+ [mybranch^] New day.
+------------
+
+Now we are ready to experiment with the merge by hand.
+
+`git merge` command, when merging two branches, uses 3-way merge
+algorithm. First, it finds the common ancestor between them.
+The command it uses is `git-merge-base`:
+
+------------
+$ mb=$(git-merge-base HEAD mybranch)
+------------
+
+The command writes the commit object name of the common ancestor
+to the standard output, so we captured its output to a variable,
+because we will be using it in the next step. BTW, the common
+ancestor commit is the "New day." commit in this case. You can
+tell it by:
+
+------------
+$ git-name-rev $mb
+my-first-tag
+------------
+
+After finding out a common ancestor commit, the second step is
+this:
+
+------------
+$ git-read-tree -m -u $mb HEAD mybranch
+------------
+
+This is the same `git-read-tree` command we have already seen,
+but it takes three trees, unlike previous examples. This reads
+the contents of each tree into different 'stage' in the index
+file (the first tree goes to stage 1, the second stage 2,
+etc.). After reading three trees into three stages, the paths
+that are the same in all three stages are 'collapsed' into stage
+0. Also paths that are the same in two of three stages are
+collapsed into stage 0, taking the SHA1 from either stage 2 or
+stage 3, whichever is different from stage 1 (i.e. only one side
+changed from the common ancestor).
+
+After 'collapsing' operation, paths that are different in three
+trees are left in non-zero stages. At this point, you can
+inspect the index file with this command:
+
+------------
+$ git-ls-files --stage
+100644 7f8b141b65fdcee47321e399a2598a235a032422 0 example
+100644 263414f423d0e4d70dae8fe53fa34614ff3e2860 1 hello
+100644 06fa6a24256dc7e560efa5687fa84b51f0263c3a 2 hello
+100644 cc44c73eb783565da5831b4d820c962954019b69 3 hello
+------------
+
+In our example of only two files, we did not have unchanged
+files so only 'example' resulted in collapsing, but in real-life
+large projects, only small number of files change in one commit,
+and this 'collapsing' tends to trivially merge most of the paths
+fairly quickly, leaving only a handful the real changes in non-zero
+stages.
+
+To look at only non-zero stages, use `\--unmerged` flag:
+
+------------
+$ git-ls-files --unmerged
+100644 263414f423d0e4d70dae8fe53fa34614ff3e2860 1 hello
+100644 06fa6a24256dc7e560efa5687fa84b51f0263c3a 2 hello
+100644 cc44c73eb783565da5831b4d820c962954019b69 3 hello
+------------
+
+The next step of merging is to merge these three versions of the
+file, using 3-way merge. This is done by giving
+`git-merge-one-file` command as one of the arguments to
+`git-merge-index` command:
+
+------------
+$ git-merge-index git-merge-one-file hello
+Auto-merging hello.
+merge: warning: conflicts during merge
+ERROR: Merge conflict in hello.
+fatal: merge program failed
+------------
+
+`git-merge-one-file` script is called with parameters to
+describe those three versions, and is responsible to leave the
+merge results in the working tree.
+It is a fairly straightforward shell script, and
+eventually calls `merge` program from RCS suite to perform a
+file-level 3-way merge. In this case, `merge` detects
+conflicts, and the merge result with conflict marks is left in
+the working tree.. This can be seen if you run `ls-files
+--stage` again at this point:
+
+------------
+$ git-ls-files --stage
+100644 7f8b141b65fdcee47321e399a2598a235a032422 0 example
+100644 263414f423d0e4d70dae8fe53fa34614ff3e2860 1 hello
+100644 06fa6a24256dc7e560efa5687fa84b51f0263c3a 2 hello
+100644 cc44c73eb783565da5831b4d820c962954019b69 3 hello
+------------
+
+This is the state of the index file and the working file after
+`git merge` returns control back to you, leaving the conflicting
+merge for you to resolve. Notice that the path `hello` is still
+unmerged, and what you see with `git diff` at this point is
+differences since stage 2 (i.e. your version).
+
+
+Publishing your work
+--------------------
+
+So we can use somebody else's work from a remote repository; but
+how can *you* prepare a repository to let other people pull from
+it?
+
+Your do your real work in your working tree that has your
+primary repository hanging under it as its `.git` subdirectory.
+You *could* make that repository accessible remotely and ask
+people to pull from it, but in practice that is not the way
+things are usually done. A recommended way is to have a public
+repository, make it reachable by other people, and when the
+changes you made in your primary working tree are in good shape,
+update the public repository from it. This is often called
+'pushing'.
+
+[NOTE]
+This public repository could further be mirrored, and that is
+how git repositories at `kernel.org` are managed.
+
+Publishing the changes from your local (private) repository to
+your remote (public) repository requires a write privilege on
+the remote machine. You need to have an SSH account there to
+run a single command, `git-receive-pack`.
+
+First, you need to create an empty repository on the remote
+machine that will house your public repository. This empty
+repository will be populated and be kept up-to-date by pushing
+into it later. Obviously, this repository creation needs to be
+done only once.
+
+[NOTE]
+`git push` uses a pair of programs,
+`git-send-pack` on your local machine, and `git-receive-pack`
+on the remote machine. The communication between the two over
+the network internally uses an SSH connection.
+
+Your private repository's git directory is usually `.git`, but
+your public repository is often named after the project name,
+i.e. `<project>.git`. Let's create such a public repository for
+project `my-git`. After logging into the remote machine, create
+an empty directory:
+
+------------
+$ mkdir my-git.git
+------------
+
+Then, make that directory into a git repository by running
+`git init-db`, but this time, since its name is not the usual
+`.git`, we do things slightly differently:
+
+------------
+$ GIT_DIR=my-git.git git-init-db
+------------
+
+Make sure this directory is available for others you want your
+changes to be pulled by via the transport of your choice. Also
+you need to make sure that you have the `git-receive-pack`
+program on the `$PATH`.
+
+[NOTE]
+Many installations of sshd do not invoke your shell as the login
+shell when you directly run programs; what this means is that if
+your login shell is `bash`, only `.bashrc` is read and not
+`.bash_profile`. As a workaround, make sure `.bashrc` sets up
+`$PATH` so that you can run `git-receive-pack` program.
+
+[NOTE]
+If you plan to publish this repository to be accessed over http,
+you should do `chmod +x my-git.git/hooks/post-update` at this
+point. This makes sure that every time you push into this
+repository, `git-update-server-info` is run.
+
+Your "public repository" is now ready to accept your changes.
+Come back to the machine you have your private repository. From
+there, run this command:
+
+------------
+$ git push <public-host>:/path/to/my-git.git master
+------------
+
+This synchronizes your public repository to match the named
+branch head (i.e. `master` in this case) and objects reachable
+from them in your current repository.
+
+As a real example, this is how I update my public git
+repository. Kernel.org mirror network takes care of the
+propagation to other publicly visible machines:
+
+------------
+$ git push master.kernel.org:/pub/scm/git/git.git/
+------------
+
+
+Packing your repository
+-----------------------
+
+Earlier, we saw that one file under `.git/objects/??/` directory
+is stored for each git object you create. This representation
+is efficient to create atomically and safely, but
+not so convenient to transport over the network. Since git objects are
+immutable once they are created, there is a way to optimize the
+storage by "packing them together". The command
+
+------------
+$ git repack
+------------
+
+will do it for you. If you followed the tutorial examples, you
+would have accumulated about 17 objects in `.git/objects/??/`
+directories by now. `git repack` tells you how many objects it
+packed, and stores the packed file in `.git/objects/pack`
+directory.
+
+[NOTE]
+You will see two files, `pack-\*.pack` and `pack-\*.idx`,
+in `.git/objects/pack` directory. They are closely related to
+each other, and if you ever copy them by hand to a different
+repository for whatever reason, you should make sure you copy
+them together. The former holds all the data from the objects
+in the pack, and the latter holds the index for random
+access.
+
+If you are paranoid, running `git-verify-pack` command would
+detect if you have a corrupt pack, but do not worry too much.
+Our programs are always perfect ;-).
+
+Once you have packed objects, you do not need to leave the
+unpacked objects that are contained in the pack file anymore.
+
+------------
+$ git prune-packed
+------------
+
+would remove them for you.
+
+You can try running `find .git/objects -type f` before and after
+you run `git prune-packed` if you are curious. Also `git
+count-objects` would tell you how many unpacked objects are in
+your repository and how much space they are consuming.
+
+[NOTE]
+`git pull` is slightly cumbersome for HTTP transport, as a
+packed repository may contain relatively few objects in a
+relatively large pack. If you expect many HTTP pulls from your
+public repository you might want to repack & prune often, or
+never.
+
+If you run `git repack` again at this point, it will say
+"Nothing to pack". Once you continue your development and
+accumulate the changes, running `git repack` again will create a
+new pack, that contains objects created since you packed your
+repository the last time. We recommend that you pack your project
+soon after the initial import (unless you are starting your
+project from scratch), and then run `git repack` every once in a
+while, depending on how active your project is.
+
+When a repository is synchronized via `git push` and `git pull`
+objects packed in the source repository are usually stored
+unpacked in the destination, unless rsync transport is used.
+While this allows you to use different packing strategies on
+both ends, it also means you may need to repack both
+repositories every once in a while.
+
+
+Working with Others
+-------------------
+
+Although git is a truly distributed system, it is often
+convenient to organize your project with an informal hierarchy
+of developers. Linux kernel development is run this way. There
+is a nice illustration (page 17, "Merges to Mainline") in Randy
+Dunlap's presentation (`http://tinyurl.com/a2jdg`).
+
+It should be stressed that this hierarchy is purely *informal*.
+There is nothing fundamental in git that enforces the "chain of
+patch flow" this hierarchy implies. You do not have to pull
+from only one remote repository.
+
+A recommended workflow for a "project lead" goes like this:
+
+1. Prepare your primary repository on your local machine. Your
+ work is done there.
+
+2. Prepare a public repository accessible to others.
++
+If other people are pulling from your repository over dumb
+transport protocols (HTTP), you need to keep this repository
+'dumb transport friendly'. After `git init-db`,
+`$GIT_DIR/hooks/post-update` copied from the standard templates
+would contain a call to `git-update-server-info` but the
+`post-update` hook itself is disabled by default -- enable it
+with `chmod +x post-update`. This makes sure `git-update-server-info`
+keeps the necessary files up-to-date.
+
+3. Push into the public repository from your primary
+ repository.
+
+4. `git repack` the public repository. This establishes a big
+ pack that contains the initial set of objects as the
+ baseline, and possibly `git prune` if the transport
+ used for pulling from your repository supports packed
+ repositories.
+
+5. Keep working in your primary repository. Your changes
+ include modifications of your own, patches you receive via
+ e-mails, and merges resulting from pulling the "public"
+ repositories of your "subsystem maintainers".
++
+You can repack this private repository whenever you feel like.
+
+6. Push your changes to the public repository, and announce it
+ to the public.
+
+7. Every once in a while, "git repack" the public repository.
+ Go back to step 5. and continue working.
+
+
+A recommended work cycle for a "subsystem maintainer" who works
+on that project and has an own "public repository" goes like this:
+
+1. Prepare your work repository, by `git clone` the public
+ repository of the "project lead". The URL used for the
+ initial cloning is stored in `.git/remotes/origin`.
+
+2. Prepare a public repository accessible to others, just like
+ the "project lead" person does.
+
+3. Copy over the packed files from "project lead" public
+ repository to your public repository, unless the "project
+ lead" repository lives on the same machine as yours. In the
+ latter case, you can use `objects/info/alternates` file to
+ point at the repository you are borrowing from.
+
+4. Push into the public repository from your primary
+ repository. Run `git repack`, and possibly `git prune` if the
+ transport used for pulling from your repository supports
+ packed repositories.
+
+5. Keep working in your primary repository. Your changes
+ include modifications of your own, patches you receive via
+ e-mails, and merges resulting from pulling the "public"
+ repositories of your "project lead" and possibly your
+ "sub-subsystem maintainers".
++
+You can repack this private repository whenever you feel
+like.
+
+6. Push your changes to your public repository, and ask your
+ "project lead" and possibly your "sub-subsystem
+ maintainers" to pull from it.
+
+7. Every once in a while, `git repack` the public repository.
+ Go back to step 5. and continue working.
+
+
+A recommended work cycle for an "individual developer" who does
+not have a "public" repository is somewhat different. It goes
+like this:
+
+1. Prepare your work repository, by `git clone` the public
+ repository of the "project lead" (or a "subsystem
+ maintainer", if you work on a subsystem). The URL used for
+ the initial cloning is stored in `.git/remotes/origin`.
+
+2. Do your work in your repository on 'master' branch.
+
+3. Run `git fetch origin` from the public repository of your
+ upstream every once in a while. This does only the first
+ half of `git pull` but does not merge. The head of the
+ public repository is stored in `.git/refs/heads/origin`.
+
+4. Use `git cherry origin` to see which ones of your patches
+ were accepted, and/or use `git rebase origin` to port your
+ unmerged changes forward to the updated upstream.
+
+5. Use `git format-patch origin` to prepare patches for e-mail
+ submission to your upstream and send it out. Go back to
+ step 2. and continue.
+
+
+Working with Others, Shared Repository Style
+--------------------------------------------
+
+If you are coming from CVS background, the style of cooperation
+suggested in the previous section may be new to you. You do not
+have to worry. git supports "shared public repository" style of
+cooperation you are probably more familiar with as well.
+
+For this, set up a public repository on a machine that is
+reachable via SSH by people with "commit privileges". Put the
+committers in the same user group and make the repository
+writable by that group. Make sure their umasks are set up to
+allow group members to write into directories other members
+have created.
+
+You, as an individual committer, then:
+
+- First clone the shared repository to a local repository:
+------------------------------------------------
+$ git clone repo.shared.xz:/pub/scm/project.git/ my-project
+$ cd my-project
+$ hack away
+------------------------------------------------
+
+- Merge the work others might have done while you were hacking
+ away:
+------------------------------------------------
+$ git pull origin
+$ test the merge result
+------------------------------------------------
+[NOTE]
+================================
+The first `git clone` would have placed the following in
+`my-project/.git/remotes/origin` file, and that's why this and
+the next step work.
+------------
+URL: repo.shared.xz:/pub/scm/project.git/ my-project
+Pull: master:origin
+------------
+================================
+
+- push your work as the new head of the shared
+ repository.
+------------------------------------------------
+$ git push origin master
+------------------------------------------------
+If somebody else pushed into the same shared repository while
+you were working locally, `git push` in the last step would
+complain, telling you that the remote `master` head does not
+fast forward. You need to pull and merge those other changes
+back before you push your work when it happens.
+
+The `git push` command without any explicit refspec parameter
+pushes the refs that exist both in the local repository and the
+remote repository. So the last `push` can be done with either
+one of these:
+------------
+$ git push origin
+$ git push repo.shared.xz:/pub/scm/project.git/
+------------
+as long as the shared repository does not have any branches
+other than `master`.
+[NOTE]
+============
+If you created your shared repository by cloning from somewhere
+else, you may have the `origin` branch. Your developers
+typically do not use that branch; remove it. Otherwise, that
+would be pushed back by the `git push origin` because your
+developers' repository would surely have `origin` branch to keep
+track of the shared repository, and would be counted as "exist
+on both ends".
+============
+
+Advanced Shared Repository Management
+-------------------------------------
+
+Being able to push into a shared repository means being able to
+write into it. If your developers are coming over the network,
+this means you, as the repository administrator, need to give
+each of them an SSH access to the shared repository machine.
+
+In some cases, though, you may not want to give a normal shell
+account to them, but want to restrict them to be able to only
+do `git push` into the repository and nothing else.
+
+You can achieve this by setting the login shell of your
+developers on the shared repository host to `git-shell` program.
+
+[NOTE]
+Most likely you would also need to list `git-shell` program in
+`/etc/shells` file.
+
+This restricts the set of commands that can be run from incoming
+SSH connection for these users to only `receive-pack` and
+`upload-pack`, so the only thing they can do are `git fetch` and
+`git push`.
+
+You still need to create UNIX user accounts for each developer,
+and put them in the same group. Make sure that the repository
+shared among these developers is writable by that group.
+
+. Initializing the shared repository with `git-init-db --shared`
+helps somewhat.
+
+. Run the following in the shared repository:
++
+------------
+$ chgrp -R $group repo.git
+$ find repo.git -type d -print | xargs chmod ug+rwx,g+s
+$ GIT_DIR=repo.git git repo-config core.sharedrepository true
+------------
+
+The above measures make sure that directories lazily created in
+`$GIT_DIR` are writable by group members. You, as the
+repository administrator, are still responsible to make sure
+your developers belong to that shared repository group and set
+their umask to a value no stricter than 027 (i.e. at least allow
+reading and searching by group members).
+
+You can implement finer grained branch policies using update
+hooks. There is a document ("control access to branches") in
+Documentation/howto by Carl Baldwin and JC outlining how to (1)
+limit access to branch per user, (2) forbid overwriting existing
+tags.
+
+
+Bundling your work together
+---------------------------
+
+It is likely that you will be working on more than one thing at
+a time. It is easy to manage those more-or-less independent tasks
+using branches with git.
+
+We have already seen how branches work previously,
+with "fun and work" example using two branches. The idea is the
+same if there are more than two branches. Let's say you started
+out from "master" head, and have some new code in the "master"
+branch, and two independent fixes in the "commit-fix" and
+"diff-fix" branches:
+
+------------
+$ git show-branch
+! [commit-fix] Fix commit message normalization.
+ ! [diff-fix] Fix rename detection.
+ * [master] Release candidate #1
+---
+ + [diff-fix] Fix rename detection.
+ + [diff-fix~1] Better common substring algorithm.
++ [commit-fix] Fix commit message normalization.
+ * [master] Release candidate #1
+++* [diff-fix~2] Pretty-print messages.
+------------
+
+Both fixes are tested well, and at this point, you want to merge
+in both of them. You could merge in 'diff-fix' first and then
+'commit-fix' next, like this:
+
+------------
+$ git merge 'Merge fix in diff-fix' master diff-fix
+$ git merge 'Merge fix in commit-fix' master commit-fix
+------------
+
+Which would result in:
+
+------------
+$ git show-branch
+! [commit-fix] Fix commit message normalization.
+ ! [diff-fix] Fix rename detection.
+ * [master] Merge fix in commit-fix
+---
+ - [master] Merge fix in commit-fix
++ * [commit-fix] Fix commit message normalization.
+ - [master~1] Merge fix in diff-fix
+ +* [diff-fix] Fix rename detection.
+ +* [diff-fix~1] Better common substring algorithm.
+ * [master~2] Release candidate #1
+++* [master~3] Pretty-print messages.
+------------
+
+However, there is no particular reason to merge in one branch
+first and the other next, when what you have are a set of truly
+independent changes (if the order mattered, then they are not
+independent by definition). You could instead merge those two
+branches into the current branch at once. First let's undo what
+we just did and start over. We would want to get the master
+branch before these two merges by resetting it to 'master~2':
+
+------------
+$ git reset --hard master~2
+------------
+
+You can make sure 'git show-branch' matches the state before
+those two 'git merge' you just did. Then, instead of running
+two 'git merge' commands in a row, you would pull these two
+branch heads (this is known as 'making an Octopus'):
+
+------------
+$ git pull . commit-fix diff-fix
+$ git show-branch
+! [commit-fix] Fix commit message normalization.
+ ! [diff-fix] Fix rename detection.
+ * [master] Octopus merge of branches 'diff-fix' and 'commit-fix'
+---
+ - [master] Octopus merge of branches 'diff-fix' and 'commit-fix'
++ * [commit-fix] Fix commit message normalization.
+ +* [diff-fix] Fix rename detection.
+ +* [diff-fix~1] Better common substring algorithm.
+ * [master~1] Release candidate #1
+++* [master~2] Pretty-print messages.
+------------
+
+Note that you should not do Octopus because you can. An octopus
+is a valid thing to do and often makes it easier to view the
+commit history if you are pulling more than two independent
+changes at the same time. However, if you have merge conflicts
+with any of the branches you are merging in and need to hand
+resolve, that is an indication that the development happened in
+those branches were not independent after all, and you should
+merge two at a time, documenting how you resolved the conflicts,
+and the reason why you preferred changes made in one side over
+the other. Otherwise it would make the project history harder
+to follow, not easier.
+
+[ to be continued.. cvsimports ]
people. The <a href="#Discussion">[Discussion]</a> section below contains much useful\r
definition and clarification - read that first.</p>\r
<p>If you are interested in using git to manage (version control)\r
-projects, use <a href="everyday.html">Everyday GIT</a> as a guide to the\r
+projects, use <a href="tutorial.html">The Tutorial</a> to get you started,\r
+and then <a href="everyday.html">Everyday GIT</a> as a guide to the\r
minimum set of commands you need to know for day-to-day work.\r
Most likely, that will get you started, and you can go a long\r
way without knowing the low level details too much.</p>\r
-<p>The <a href="tutorial.html">tutorial</a> document covers how things\r
+<p>The <a href="core-tutorial.html">Core tutorial</a> document covers how things\r
internally work.</p>\r
<p>If you are migrating from CVS, <a href="cvs-migration.html">cvs\r
migration</a> document may be helpful after you finish the\r
</div>\r
<div id="footer">\r
<div id="footer-text">\r
-Last updated 06-Jan-2006 17:12:47 PDT\r
+Last updated 22-Jan-2006 23:54:19 PDT\r
</div>\r
</div>\r
</body>\r
definition and clarification - read that first.
If you are interested in using git to manage (version control)
-projects, use link:everyday.html[Everyday GIT] as a guide to the
+projects, use link:tutorial.html[The Tutorial] to get you started,
+and then link:everyday.html[Everyday GIT] as a guide to the
minimum set of commands you need to know for day-to-day work.
Most likely, that will get you started, and you can go a long
way without knowing the low level details too much.
-The link:tutorial.html[tutorial] document covers how things
+The link:core-tutorial.html[Core tutorial] document covers how things
internally work.
If you are migrating from CVS, link:cvs-migration.html[cvs
padding-left: 0.5em;\r
}\r
</style>\r
-<title>A short git tutorial</title>\r
+<title>A tutorial introduction to git</title>\r
</head>\r
<body>\r
<div id="header">\r
-<h1>A short git tutorial</h1>\r
+<h1>A tutorial introduction to git</h1>\r
</div>\r
-<h2>Introduction</h2>\r
+<div id="preamble">\r
<div class="sectionbody">\r
-<p>This is trying to be a short tutorial on setting up and using a git\r
-repository, mainly because being hands-on and using explicit examples is\r
-often the best way of explaining what is going on.</p>\r
-<p>In normal life, most people wouldn't use the "core" git programs\r
-directly, but rather script around them to make them more palatable.\r
-Understanding the core git stuff may help some people get those scripts\r
-done, though, and it may also be instructive in helping people\r
-understand what it is that the higher-level helper scripts are actually\r
-doing.</p>\r
-<p>The core git is often called "plumbing", with the prettier user\r
-interfaces on top of it called "porcelain". You may not want to use the\r
-plumbing directly very often, but it can be good to know what the\r
-plumbing does for when the porcelain isn't flushing.</p>\r
-<p>The material presented here often goes deep describing how things\r
-work internally. If you are mostly interested in using git as a\r
-SCM, you can skip them during your first pass.</p>\r
-<div class="admonitionblock">\r
-<table><tr>\r
-<td class="icon">\r
-<div class="title">Note</div>\r
-</td>\r
-<td class="content">And those "too deep" descriptions are often marked as Note.</td>\r
-</tr></table>\r
-</div>\r
-<div class="admonitionblock">\r
-<table><tr>\r
-<td class="icon">\r
-<div class="title">Note</div>\r
-</td>\r
-<td class="content">If you are already familiar with another version control system,\r
-like CVS, you may want to take a look at\r
-<a href="everyday.html">Everyday GIT in 20 commands or so</a> first\r
-before reading this.</td>\r
-</tr></table>\r
-</div>\r
-</div>\r
-<h2>Creating a git repository</h2>\r
-<div class="sectionbody">\r
-<p>Creating a new git repository couldn't be easier: all git repositories start\r
-out empty, and the only thing you need to do is find yourself a\r
-subdirectory that you want to use as a working tree - either an empty\r
-one for a totally new project, or an existing working tree that you want\r
-to import into git.</p>\r
-<p>For our first example, we're going to start a totally new repository from\r
-scratch, with no pre-existing files, and we'll call it <tt>git-tutorial</tt>.\r
-To start up, create a subdirectory for it, change into that\r
-subdirectory, and initialize the git infrastructure with <tt>git-init-db</tt>:</p>\r
+<p>This tutorial explains how to import a new project into git, make\r
+changes to it, and share changes with other developers.</p>\r
+<p>First, note that you can get documentation for a command such as "git\r
+diff" with:</p>\r
<div class="listingblock">\r
<div class="content">\r
-<pre><tt>$ mkdir git-tutorial\r
-$ cd git-tutorial\r
-$ git-init-db</tt></pre>\r
+<pre><tt>$ man git-diff</tt></pre>\r
</div></div>\r
-<p>to which git will reply</p>\r
-<div class="listingblock">\r
-<div class="content">\r
-<pre><tt>defaulting to local storage area</tt></pre>\r
-</div></div>\r
-<p>which is just git's way of saying that you haven't been doing anything\r
-strange, and that it will have created a local <tt>.git</tt> directory setup for\r
-your new project. You will now have a <tt>.git</tt> directory, and you can\r
-inspect that with <tt>ls</tt>. For your new empty project, it should show you\r
-three entries, among other things:</p>\r
-<ul>\r
-<li>\r
-<p>\r
-a symlink called <tt>HEAD</tt>, pointing to <tt>refs/heads/master</tt> (if your\r
- platform does not have native symlinks, it is a file containing the\r
- line "ref: refs/heads/master")\r
-</p>\r
-<p>Don't worry about the fact that the file that the <tt>HEAD</tt> link points to\r
-doesn't even exist yet — you haven't created the commit that will\r
-start your <tt>HEAD</tt> development branch yet.</p>\r
-</li>\r
-<li>\r
-<p>\r
-a subdirectory called <tt>objects</tt>, which will contain all the\r
- objects of your project. You should never have any real reason to\r
- look at the objects directly, but you might want to know that these\r
- objects are what contains all the real <em>data</em> in your repository.\r
-</p>\r
-</li>\r
-<li>\r
-<p>\r
-a subdirectory called <tt>refs</tt>, which contains references to objects.\r
-</p>\r
-</li>\r
-</ul>\r
-<p>In particular, the <tt>refs</tt> subdirectory will contain two other\r
-subdirectories, named <tt>heads</tt> and <tt>tags</tt> respectively. They do\r
-exactly what their names imply: they contain references to any number\r
-of different <em>heads</em> of development (aka <em>branches</em>), and to any\r
-<em>tags</em> that you have created to name specific versions in your\r
-repository.</p>\r
-<p>One note: the special <tt>master</tt> head is the default branch, which is\r
-why the <tt>.git/HEAD</tt> file was created as a symlink to it even if it\r
-doesn't yet exist. Basically, the <tt>HEAD</tt> link is supposed to always\r
-point to the branch you are working on right now, and you always\r
-start out expecting to work on the <tt>master</tt> branch.</p>\r
-<p>However, this is only a convention, and you can name your branches\r
-anything you want, and don't have to ever even <em>have</em> a <tt>master</tt>\r
-branch. A number of the git tools will assume that <tt>.git/HEAD</tt> is\r
-valid, though.</p>\r
-<div class="admonitionblock">\r
-<table><tr>\r
-<td class="icon">\r
-<div class="title">Note</div>\r
-</td>\r
-<td class="content">An <em>object</em> is identified by its 160-bit SHA1 hash, aka <em>object name</em>,\r
-and a reference to an object is always the 40-byte hex\r
-representation of that SHA1 name. The files in the <tt>refs</tt>\r
-subdirectory are expected to contain these hex references\r
-(usually with a final <tt>'\n'</tt> at the end), and you should thus\r
-expect to see a number of 41-byte files containing these\r
-references in these <tt>refs</tt> subdirectories when you actually start\r
-populating your tree.</td>\r
-</tr></table>\r
</div>\r
-<div class="admonitionblock">\r
-<table><tr>\r
-<td class="icon">\r
-<div class="title">Note</div>\r
-</td>\r
-<td class="content">An advanced user may want to take a look at the\r
-<a href="repository-layout.html">repository layout</a> document\r
-after finishing this tutorial.</td>\r
-</tr></table>\r
</div>\r
-<p>You have now created your first git repository. Of course, since it's\r
-empty, that's not very useful, so let's start populating it with data.</p>\r
-</div>\r
-<h2>Populating a git repository</h2>\r
+<h2>Importing a new project</h2>\r
<div class="sectionbody">\r
-<p>We'll keep this simple and stupid, so we'll start off with populating a\r
-few trivial files just to get a feel for it.</p>\r
-<p>Start off with just creating any random files that you want to maintain\r
-in your git repository. We'll start off with a few bad examples, just to\r
-get a feel for how this works:</p>\r
+<p>Assume you have a tarball project.tar.gz with your initial work. You\r
+can place it under git revision control as follows.</p>\r
<div class="listingblock">\r
<div class="content">\r
-<pre><tt>$ echo "Hello World" >hello\r
-$ echo "Silly example" >example</tt></pre>\r
+<pre><tt>$ tar xzf project.tar.gz\r
+$ cd project\r
+$ git init-db</tt></pre>\r
</div></div>\r
-<p>you have now created two files in your working tree (aka <em>working directory</em>), but to\r
-actually check in your hard work, you will have to go through two steps:</p>\r
-<ul>\r
-<li>\r
-<p>\r
-fill in the <em>index</em> file (aka <em>cache</em>) with the information about your\r
- working tree state.\r
-</p>\r
-</li>\r
-<li>\r
-<p>\r
-commit that index file as an object.\r
-</p>\r
-</li>\r
-</ul>\r
-<p>The first step is trivial: when you want to tell git about any changes\r
-to your working tree, you use the <tt>git-update-index</tt> program. That\r
-program normally just takes a list of filenames you want to update, but\r
-to avoid trivial mistakes, it refuses to add new entries to the index\r
-(or remove existing ones) unless you explicitly tell it that you're\r
-adding a new entry with the <tt>--add</tt> flag (or removing an entry with the\r
-<tt>--remove</tt>) flag.</p>\r
-<p>So to populate the index with the two files you just created, you can do</p>\r
+<p>Git will reply</p>\r
<div class="listingblock">\r
<div class="content">\r
-<pre><tt>$ git-update-index --add hello example</tt></pre>\r
-</div></div>\r
-<p>and you have now told git to track those two files.</p>\r
-<p>In fact, as you did that, if you now look into your object directory,\r
-you'll notice that git will have added two new objects to the object\r
-database. If you did exactly the steps above, you should now be able to do</p>\r
-<div class="listingblock">\r
-<div class="content">\r
-<pre><tt>$ ls .git/objects/??/*</tt></pre>\r
+<pre><tt>defaulting to local storage area</tt></pre>\r
</div></div>\r
-<p>and see two files:</p>\r
+<p>You've now initialized the working directory—you may notice a new\r
+directory created, named ".git". Tell git that you want it to track\r
+every file under the current directory with</p>\r
<div class="listingblock">\r
<div class="content">\r
-<pre><tt>.git/objects/55/7db03de997c86a4a028e1ebd3a1ceb225be238\r
-.git/objects/f2/4c74a2e500f5ee1332c86b94199f52b1d1d962</tt></pre>\r
+<pre><tt>$ git add .</tt></pre>\r
</div></div>\r
-<p>which correspond with the objects with names of 557db… and f24c7..\r
-respectively.</p>\r
-<p>If you want to, you can use <tt>git-cat-file</tt> to look at those objects, but\r
-you'll have to use the object name, not the filename of the object:</p>\r
+<p>Finally,</p>\r
<div class="listingblock">\r
<div class="content">\r
-<pre><tt>$ git-cat-file -t 557db03de997c86a4a028e1ebd3a1ceb225be238</tt></pre>\r
+<pre><tt>$ git commit -a</tt></pre>\r
</div></div>\r
-<p>where the <tt>-t</tt> tells <tt>git-cat-file</tt> to tell you what the "type" of the\r
-object is. git will tell you that you have a "blob" object (ie just a\r
-regular file), and you can see the contents with</p>\r
+<p>will prompt you for a commit message, then record the current state\r
+of all the files to the repository.</p>\r
+<p>Try modifying some files, then run</p>\r
<div class="listingblock">\r
<div class="content">\r
-<pre><tt>$ git-cat-file "blob" 557db03</tt></pre>\r
+<pre><tt>$ git diff</tt></pre>\r
</div></div>\r
-<p>which will print out "Hello World". The object 557db03 is nothing\r
-more than the contents of your file <tt>hello</tt>.</p>\r
-<div class="admonitionblock">\r
-<table><tr>\r
-<td class="icon">\r
-<div class="title">Note</div>\r
-</td>\r
-<td class="content">Don't confuse that object with the file <tt>hello</tt> itself. The\r
-object is literally just those specific <strong>contents</strong> of the file, and\r
-however much you later change the contents in file <tt>hello</tt>, the object\r
-we just looked at will never change. Objects are immutable.</td>\r
-</tr></table>\r
-</div>\r
-<div class="admonitionblock">\r
-<table><tr>\r
-<td class="icon">\r
-<div class="title">Note</div>\r
-</td>\r
-<td class="content">The second example demonstrates that you can\r
-abbreviate the object name to only the first several\r
-hexadecimal digits in most places.</td>\r
-</tr></table>\r
-</div>\r
-<p>Anyway, as we mentioned previously, you normally never actually take a\r
-look at the objects themselves, and typing long 40-character hex\r
-names is not something you'd normally want to do. The above digression\r
-was just to show that <tt>git-update-index</tt> did something magical, and\r
-actually saved away the contents of your files into the git object\r
-database.</p>\r
-<p>Updating the index did something else too: it created a <tt>.git/index</tt>\r
-file. This is the index that describes your current working tree, and\r
-something you should be very aware of. Again, you normally never worry\r
-about the index file itself, but you should be aware of the fact that\r
-you have not actually really "checked in" your files into git so far,\r
-you've only <strong>told</strong> git about them.</p>\r
-<p>However, since git knows about them, you can now start using some of the\r
-most basic git commands to manipulate the files or look at their status.</p>\r
-<p>In particular, let's not even check in the two files into git yet, we'll\r
-start off by adding another line to <tt>hello</tt> first:</p>\r
+<p>to review your changes. When you're done,</p>\r
<div class="listingblock">\r
<div class="content">\r
-<pre><tt>$ echo "It's a new day for git" >>hello</tt></pre>\r
+<pre><tt>$ git commit -a</tt></pre>\r
</div></div>\r
-<p>and you can now, since you told git about the previous state of <tt>hello</tt>, ask\r
-git what has changed in the tree compared to your old index, using the\r
-<tt>git-diff-files</tt> command:</p>\r
+<p>will again prompt your for a message describing the change, and then\r
+record the new versions of the modified files.</p>\r
+<p>A note on commit messages: Though not required, it's a good idea to\r
+begin the commit message with a single short (less than 50 character)\r
+line summarizing the change, followed by a blank line and then a more\r
+thorough description. Tools that turn commits into email, for\r
+example, use the first line on the Subject line and the rest of the\r
+commit in the body.</p>\r
+<p>To add a new file, first create the file, then</p>\r
<div class="listingblock">\r
<div class="content">\r
-<pre><tt>$ git-diff-files</tt></pre>\r
+<pre><tt>$ git add path/to/new/file</tt></pre>\r
</div></div>\r
-<p>Oops. That wasn't very readable. It just spit out its own internal\r
-version of a <tt>diff</tt>, but that internal version really just tells you\r
-that it has noticed that "hello" has been modified, and that the old object\r
-contents it had have been replaced with something else.</p>\r
-<p>To make it readable, we can tell git-diff-files to output the\r
-differences as a patch, using the <tt>-p</tt> flag:</p>\r
+<p>then commit as usual. No special command is required when removing a\r
+file; just remove it, then commit.</p>\r
+<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-diff-files -p\r
-diff --git a/hello b/hello\r
-index 557db03..263414f 100644\r
---- a/hello\r
-+++ b/hello\r
-@@ -1 +1,2 @@\r
- Hello World\r
-+It's a new day for git</tt></pre>\r
+<pre><tt>$ git whatchanged</tt></pre>\r
</div></div>\r
-<p>i.e. the diff of the change we caused by adding another line to <tt>hello</tt>.</p>\r
-<p>In other words, <tt>git-diff-files</tt> always shows us the difference between\r
-what is recorded in the index, and what is currently in the working\r
-tree. That's very useful.</p>\r
-<p>A common shorthand for <tt>git-diff-files -p</tt> is to just write <tt>git\r
-diff</tt>, which will do the same thing.</p>\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 diff\r
-diff --git a/hello b/hello\r
-index 557db03..263414f 100644\r
---- a/hello\r
-+++ b/hello\r
-@@ -1 +1,2 @@\r
- Hello World\r
-+It's a new day for git</tt></pre>\r
+<pre><tt>$ git whatchanged -p</tt></pre>\r
</div></div>\r
</div>\r
-<h2>Committing git state</h2>\r
+<h2>Managing branches</h2>\r
<div class="sectionbody">\r
-<p>Now, we want to go to the next stage in git, which is to take the files\r
-that git knows about in the index, and commit them as a real tree. We do\r
-that in two phases: creating a <em>tree</em> object, and committing that <em>tree</em>\r
-object as a <em>commit</em> object together with an explanation of what the\r
-tree was all about, along with information of how we came to that state.</p>\r
-<p>Creating a tree object is trivial, and is done with <tt>git-write-tree</tt>.\r
-There are no options or other input: git-write-tree will take the\r
-current index state, and write an object that describes that whole\r
-index. In other words, we're now tying together all the different\r
-filenames with their contents (and their permissions), and we're\r
-creating the equivalent of a git "directory" object:</p>\r
-<div class="listingblock">\r
-<div class="content">\r
-<pre><tt>$ git-write-tree</tt></pre>\r
-</div></div>\r
-<p>and this will just output the name of the resulting tree, in this case\r
-(if you have done exactly as I've described) it should be</p>\r
-<div class="listingblock">\r
-<div class="content">\r
-<pre><tt>8988da15d077d4829fc51d8544c097def6644dbb</tt></pre>\r
-</div></div>\r
-<p>which is another incomprehensible object name. Again, if you want to,\r
-you can use <tt>git-cat-file -t 8988d...</tt> to see that this time the object\r
-is not a "blob" object, but a "tree" object (you can also use\r
-<tt>git-cat-file</tt> to actually output the raw object contents, but you'll see\r
-mainly a binary mess, so that's less interesting).</p>\r
-<p>However — normally you'd never use <tt>git-write-tree</tt> on its own, because\r
-normally you always commit a tree into a commit object using the\r
-<tt>git-commit-tree</tt> command. In fact, it's easier to not actually use\r
-<tt>git-write-tree</tt> on its own at all, but to just pass its result in as an\r
-argument to <tt>git-commit-tree</tt>.</p>\r
-<p><tt>git-commit-tree</tt> normally takes several arguments — it wants to know\r
-what the <em>parent</em> of a commit was, but since this is the first commit\r
-ever in this new repository, and it has no parents, we only need to pass in\r
-the object name of the tree. However, <tt>git-commit-tree</tt>\r
-also wants to get a commit message\r
-on its standard input, and it will write out the resulting object name for the\r
-commit to its standard output.</p>\r
-<p>And this is where we create the <tt>.git/refs/heads/master</tt> file\r
-which is pointed at by <tt>HEAD</tt>. This file is supposed to contain\r
-the reference to the top-of-tree of the master branch, and since\r
-that's exactly what <tt>git-commit-tree</tt> spits out, we can do this\r
-all with a sequence of simple shell commands:</p>\r
+<p>A single git repository can maintain multiple branches of\r
+development. To create a new branch named "experimental", use</p>\r
<div class="listingblock">\r
<div class="content">\r
-<pre><tt>$ tree=$(git-write-tree)\r
-$ commit=$(echo 'Initial commit' | git-commit-tree $tree)\r
-$ git-update-ref HEAD $commit</tt></pre>\r
+<pre><tt>$ git branch experimental</tt></pre>\r
</div></div>\r
-<p>which will say:</p>\r
+<p>If you now run</p>\r
<div class="listingblock">\r
<div class="content">\r
-<pre><tt>Committing initial tree 8988da15d077d4829fc51d8544c097def6644dbb</tt></pre>\r
-</div></div>\r
-<p>just to warn you about the fact that it created a totally new commit\r
-that is not related to anything else. Normally you do this only <strong>once</strong>\r
-for a project ever, and all later commits will be parented on top of an\r
-earlier commit, and you'll never see this "Committing initial tree"\r
-message ever again.</p>\r
-<p>Again, normally you'd never actually do this by hand. There is a\r
-helpful script called <tt>git commit</tt> that will do all of this for you. So\r
-you could have just written <tt>git commit</tt>\r
-instead, and it would have done the above magic scripting for you.</p>\r
-</div>\r
-<h2>Making a change</h2>\r
-<div class="sectionbody">\r
-<p>Remember how we did the <tt>git-update-index</tt> on file <tt>hello</tt> and then we\r
-changed <tt>hello</tt> afterward, and could compare the new state of <tt>hello</tt> with the\r
-state we saved in the index file?</p>\r
-<p>Further, remember how I said that <tt>git-write-tree</tt> writes the contents\r
-of the <strong>index</strong> file to the tree, and thus what we just committed was in\r
-fact the <strong>original</strong> contents of the file <tt>hello</tt>, not the new ones. We did\r
-that on purpose, to show the difference between the index state, and the\r
-state in the working tree, and how they don't have to match, even\r
-when we commit things.</p>\r
-<p>As before, if we do <tt>git-diff-files -p</tt> in our git-tutorial project,\r
-we'll still see the same difference we saw last time: the index file\r
-hasn't changed by the act of committing anything. However, now that we\r
-have committed something, we can also learn to use a new command:\r
-<tt>git-diff-index</tt>.</p>\r
-<p>Unlike <tt>git-diff-files</tt>, which showed the difference between the index\r
-file and the working tree, <tt>git-diff-index</tt> shows the differences\r
-between a committed <strong>tree</strong> and either the index file or the working\r
-tree. In other words, <tt>git-diff-index</tt> wants a tree to be diffed\r
-against, and before we did the commit, we couldn't do that, because we\r
-didn't have anything to diff against.</p>\r
-<p>But now we can do</p>\r
-<div class="listingblock">\r
-<div class="content">\r
-<pre><tt>$ git-diff-index -p HEAD</tt></pre>\r
+<pre><tt>$ git branch</tt></pre>\r
</div></div>\r
-<p>(where <tt>-p</tt> has the same meaning as it did in <tt>git-diff-files</tt>), and it\r
-will show us the same difference, but for a totally different reason.\r
-Now we're comparing the working tree not against the index file,\r
-but against the tree we just wrote. It just so happens that those two\r
-are obviously the same, so we get the same result.</p>\r
-<p>Again, because this is a common operation, you can also just shorthand\r
-it with</p>\r
+<p>you'll get a list of all existing branches:</p>\r
<div class="listingblock">\r
<div class="content">\r
-<pre><tt>$ git diff HEAD</tt></pre>\r
+<pre><tt> experimental\r
+* master</tt></pre>\r
</div></div>\r
-<p>which ends up doing the above for you.</p>\r
-<p>In other words, <tt>git-diff-index</tt> normally compares a tree against the\r
-working tree, but when given the <tt>--cached</tt> flag, it is told to\r
-instead compare against just the index cache contents, and ignore the\r
-current working tree state entirely. Since we just wrote the index\r
-file to HEAD, doing <tt>git-diff-index --cached -p HEAD</tt> should thus return\r
-an empty set of differences, and that's exactly what it does.</p>\r
-<div class="admonitionblock">\r
-<table><tr>\r
-<td class="icon">\r
-<div class="title">Note</div>\r
-</td>\r
-<td class="content">\r
-<p><tt>git-diff-index</tt> really always uses the index for its\r
-comparisons, and saying that it compares a tree against the working\r
-tree is thus not strictly accurate. In particular, the list of\r
-files to compare (the "meta-data") <strong>always</strong> comes from the index file,\r
-regardless of whether the <tt>--cached</tt> flag is used or not. The <tt>--cached</tt>\r
-flag really only determines whether the file <strong>contents</strong> to be compared\r
-come from the working tree or not.</p>\r
-<p>This is not hard to understand, as soon as you realize that git simply\r
-never knows (or cares) about files that it is not told about\r
-explicitly. git will never go <strong>looking</strong> for files to compare, it\r
-expects you to tell it what the files are, and that's what the index\r
-is there for.</p>\r
-</td>\r
-</tr></table>\r
-</div>\r
-<p>However, our next step is to commit the <strong>change</strong> we did, and again, to\r
-understand what's going on, keep in mind the difference between "working\r
-tree contents", "index file" and "committed tree". We have changes\r
-in the working tree that we want to commit, and we always have to\r
-work through the index file, so the first thing we need to do is to\r
-update the index cache:</p>\r
+<p>The "experimental" branch is the one you just created, and the\r
+"master" branch is a default branch that was created for you\r
+automatically. The asterisk marks the branch you are currently on;\r
+type</p>\r
<div class="listingblock">\r
<div class="content">\r
-<pre><tt>$ git-update-index hello</tt></pre>\r
+<pre><tt>$ git checkout experimental</tt></pre>\r
</div></div>\r
-<p>(note how we didn't need the <tt>--add</tt> flag this time, since git knew\r
-about the file already).</p>\r
-<p>Note what happens to the different <tt>git-diff-*</tt> versions here. After\r
-we've updated <tt>hello</tt> in the index, <tt>git-diff-files -p</tt> now shows no\r
-differences, but <tt>git-diff-index -p HEAD</tt> still *does* show that the\r
-current state is different from the state we committed. In fact, now\r
-<tt>git-diff-index</tt> shows the same difference whether we use the <tt>—cached</tt>\r
-flag or not, since now the index is coherent with the working tree.</p>\r
-<p>Now, since we've updated <tt>hello</tt> in the index, we can commit the new\r
-version. We could do it by writing the tree by hand again, and\r
-committing the tree (this time we'd have to use the <tt>-p HEAD</tt> flag to\r
-tell commit that the HEAD was the <strong>parent</strong> of the new commit, and that\r
-this wasn't an initial commit any more), but you've done that once\r
-already, so let's just use the helpful script this time:</p>\r
+<p>to switch to the experimental branch. Now edit a file, commit the\r
+change, and switch back to the master branch:</p>\r
<div class="listingblock">\r
<div class="content">\r
-<pre><tt>$ git commit</tt></pre>\r
+<pre><tt>(edit file)\r
+$ git commit -a\r
+$ git checkout master</tt></pre>\r
</div></div>\r
-<p>which starts an editor for you to write the commit message and tells you\r
-a bit about what you have done.</p>\r
-<p>Write whatever message you want, and all the lines that start with <em>#</em>\r
-will be pruned out, and the rest will be used as the commit message for\r
-the change. If you decide you don't want to commit anything after all at\r
-this point (you can continue to edit things and update the index), you\r
-can just leave an empty message. Otherwise <tt>git commit</tt> will commit\r
-the change for you.</p>\r
-<p>You've now made your first real git commit. And if you're interested in\r
-looking at what <tt>git commit</tt> really does, feel free to investigate:\r
-it's a few very simple shell scripts to generate the helpful (?) commit\r
-message headers, and a few one-liners that actually do the\r
-commit itself (<tt>git-commit</tt>).</p>\r
-</div>\r
-<h2>Inspecting Changes</h2>\r
-<div class="sectionbody">\r
-<p>While creating changes is useful, it's even more useful if you can tell\r
-later what changed. The most useful command for this is another of the\r
-<tt>diff</tt> family, namely <tt>git-diff-tree</tt>.</p>\r
-<p><tt>git-diff-tree</tt> can be given two arbitrary trees, and it will tell you the\r
-differences between them. Perhaps even more commonly, though, you can\r
-give it just a single commit object, and it will figure out the parent\r
-of that commit itself, and show the difference directly. Thus, to get\r
-the same diff that we've already seen several times, we can now do</p>\r
+<p>Check that the change you made is no longer visible, since it was\r
+made on the experimental branch and you're back on the master branch.</p>\r
+<p>You can make a different change on the master branch:</p>\r
<div class="listingblock">\r
<div class="content">\r
-<pre><tt>$ git-diff-tree -p HEAD</tt></pre>\r
+<pre><tt>(edit file)\r
+$ git commit -a</tt></pre>\r
</div></div>\r
-<p>(again, <tt>-p</tt> means to show the difference as a human-readable patch),\r
-and it will show what the last commit (in <tt>HEAD</tt>) actually changed.</p>\r
-<div class="admonitionblock">\r
-<table><tr>\r
-<td class="icon">\r
-<div class="title">Note</div>\r
-</td>\r
-<td class="content">\r
-<p>Here is an ASCII art by Jon Loeliger that illustrates how\r
-various diff-* commands compare things.</p>\r
-<div class="literalblock">\r
-<div class="content">\r
-<pre><tt> diff-tree\r
- +----+\r
- | |\r
- | |\r
- V V\r
- +-----------+\r
- | Object DB |\r
- | Backing |\r
- | Store |\r
- +-----------+\r
- ^ ^\r
- | |\r
- | | diff-index --cached\r
- | |\r
-diff-index | V\r
- | +-----------+\r
- | | Index |\r
- | | "cache" |\r
- | +-----------+\r
- | ^\r
- | |\r
- | | diff-files\r
- | |\r
- V V\r
- +-----------+\r
- | Working |\r
- | Directory |\r
- +-----------+</tt></pre>\r
-</div></div>\r
-</td>\r
-</tr></table>\r
-</div>\r
-<p>More interestingly, you can also give <tt>git-diff-tree</tt> the <tt>-v</tt> flag, which\r
-tells it to also show the commit message and author and date of the\r
-commit, and you can tell it to show a whole series of diffs.\r
-Alternatively, you can tell it to be "silent", and not show the diffs at\r
-all, but just show the actual commit message.</p>\r
-<p>In fact, together with the <tt>git-rev-list</tt> program (which generates a\r
-list of revisions), <tt>git-diff-tree</tt> ends up being a veritable fount of\r
-changes. A trivial (but very useful) script called <tt>git-whatchanged</tt> is\r
-included with git which does exactly this, and shows a log of recent\r
-activities.</p>\r
-<p>To see the whole history of our pitiful little git-tutorial project, you\r
-can do</p>\r
+<p>at this point the two branches have diverged, with different changes\r
+made in each. To merge the changes made in the two branches, run</p>\r
<div class="listingblock">\r
<div class="content">\r
-<pre><tt>$ git log</tt></pre>\r
+<pre><tt>$ git pull . experimental</tt></pre>\r
</div></div>\r
-<p>which shows just the log messages, or if we want to see the log together\r
-with the associated patches use the more complex (and much more\r
-powerful)</p>\r
+<p>If the changes don't conflict, you're done. If there are conflicts,\r
+markers will be left in the problematic files showing the conflict;</p>\r
<div class="listingblock">\r
<div class="content">\r
-<pre><tt>$ git-whatchanged -p --root</tt></pre>\r
+<pre><tt>$ git diff</tt></pre>\r
</div></div>\r
-<p>and you will see exactly what has changed in the repository over its\r
-short history.</p>\r
-<div class="admonitionblock">\r
-<table><tr>\r
-<td class="icon">\r
-<div class="title">Note</div>\r
-</td>\r
-<td class="content">The <tt>--root</tt> flag is a flag to <tt>git-diff-tree</tt> to tell it to\r
-show the initial aka <em>root</em> commit too. Normally you'd probably not\r
-want to see the initial import diff, but since the tutorial project\r
-was started from scratch and is so small, we use it to make the result\r
-a bit more interesting.</td>\r
-</tr></table>\r
-</div>\r
-<p>With that, you should now be having some inkling of what git does, and\r
-can explore on your own.</p>\r
-<div class="admonitionblock">\r
-<table><tr>\r
-<td class="icon">\r
-<div class="title">Note</div>\r
-</td>\r
-<td class="content">Most likely, you are not directly using the core\r
-git Plumbing commands, but using Porcelain like Cogito on top\r
-of it. Cogito works a bit differently and you usually do not\r
-have to run <tt>git-update-index</tt> yourself for changed files (you\r
-do tell underlying git about additions and removals via\r
-<tt>cg-add</tt> and <tt>cg-rm</tt> commands). Just before you make a commit\r
-with <tt>cg-commit</tt>, Cogito figures out which files you modified,\r
-and runs <tt>git-update-index</tt> on them for you.</td>\r
-</tr></table>\r
-</div>\r
-</div>\r
-<h2>Tagging a version</h2>\r
-<div class="sectionbody">\r
-<p>In git, there are two kinds of tags, a "light" one, and an "annotated tag".</p>\r
-<p>A "light" tag is technically nothing more than a branch, except we put\r
-it in the <tt>.git/refs/tags/</tt> subdirectory instead of calling it a <tt>head</tt>.\r
-So the simplest form of tag involves nothing more than</p>\r
+<p>will show this. Once you've edited the files to resolve the\r
+conflicts,</p>\r
<div class="listingblock">\r
<div class="content">\r
-<pre><tt>$ git tag my-first-tag</tt></pre>\r
+<pre><tt>$ git commit -a</tt></pre>\r
</div></div>\r
-<p>which just writes the current <tt>HEAD</tt> into the <tt>.git/refs/tags/my-first-tag</tt>\r
-file, after which point you can then use this symbolic name for that\r
-particular state. You can, for example, do</p>\r
+<p>will commit the result of the merge. Finally,</p>\r
<div class="listingblock">\r
<div class="content">\r
-<pre><tt>$ git diff my-first-tag</tt></pre>\r
+<pre><tt>$ gitk</tt></pre>\r
</div></div>\r
-<p>to diff your current state against that tag (which at this point will\r
-obviously be an empty diff, but if you continue to develop and commit\r
-stuff, you can use your tag as an "anchor-point" to see what has changed\r
-since you tagged it.</p>\r
-<p>An "annotated tag" is actually a real git object, and contains not only a\r
-pointer to the state you want to tag, but also a small tag name and\r
-message, along with optionally a PGP signature that says that yes,\r
-you really did\r
-that tag. You create these annotated tags with either the <tt>-a</tt> or\r
-<tt>-s</tt> flag to <tt>git tag</tt>:</p>\r
+<p>will show a nice graphical representation of the resulting history.</p>\r
+<p>If you develop on a branch crazy-idea, then regret it, you can always\r
+delete the branch with</p>\r
<div class="listingblock">\r
<div class="content">\r
-<pre><tt>$ git tag -s <tagname></tt></pre>\r
+<pre><tt>$ git branch -D crazy-idea</tt></pre>\r
</div></div>\r
-<p>which will sign the current <tt>HEAD</tt> (but you can also give it another\r
-argument that specifies the thing to tag, ie you could have tagged the\r
-current <tt>mybranch</tt> point by using <tt>git tag <tagname> mybranch</tt>).</p>\r
-<p>You normally only do signed tags for major releases or things\r
-like that, while the light-weight tags are useful for any marking you\r
-want to do — any time you decide that you want to remember a certain\r
-point, just create a private tag for it, and you have a nice symbolic\r
-name for the state at that point.</p>\r
+<p>Branches are cheap and easy, so this is a good way to try something\r
+out.</p>\r
</div>\r
-<h2>Copying repositories</h2>\r
+<h2>Using git for collaboration</h2>\r
<div class="sectionbody">\r
-<p>git repositories are normally totally self-sufficient and relocatable\r
-Unlike CVS, for example, there is no separate notion of\r
-"repository" and "working tree". A git repository normally <strong>is</strong> the\r
-working tree, with the local git information hidden in the <tt>.git</tt>\r
-subdirectory. There is nothing else. What you see is what you got.</p>\r
-<div class="admonitionblock">\r
-<table><tr>\r
-<td class="icon">\r
-<div class="title">Note</div>\r
-</td>\r
-<td class="content">You can tell git to split the git internal information from\r
-the directory that it tracks, but we'll ignore that for now: it's not\r
-how normal projects work, and it's really only meant for special uses.\r
-So the mental model of "the git information is always tied directly to\r
-the working tree that it describes" may not be technically 100%\r
-accurate, but it's a good model for all normal use.</td>\r
-</tr></table>\r
-</div>\r
-<p>This has two implications:</p>\r
-<ul>\r
-<li>\r
-<p>\r
-if you grow bored with the tutorial repository you created (or you've\r
- made a mistake and want to start all over), you can just do simple\r
-</p>\r
+<p>Suppose that Alice has started a new project with a git repository in\r
+/home/alice/project, and that Bob, who has a home directory on the\r
+same machine, wants to contribute.</p>\r
+<p>Bob begins with:</p>\r
<div class="listingblock">\r
<div class="content">\r
-<pre><tt>$ rm -rf git-tutorial</tt></pre>\r
+<pre><tt>$ git clone /home/alice/project myrepo</tt></pre>\r
</div></div>\r
-<p>and it will be gone. There's no external repository, and there's no\r
-history outside the project you created.</p>\r
-</li>\r
-<li>\r
-<p>\r
-if you want to move or duplicate a git repository, you can do so. There\r
- is <tt>git clone</tt> command, but if all you want to do is just to\r
- create a copy of your repository (with all the full history that\r
- went along with it), you can do so with a regular\r
- <tt>cp -a git-tutorial new-git-tutorial</tt>.\r
-</p>\r
-<p>Note that when you've moved or copied a git repository, your git index\r
-file (which caches various information, notably some of the "stat"\r
-information for the files involved) will likely need to be refreshed.\r
-So after you do a <tt>cp -a</tt> to create a new copy, you'll want to do</p>\r
+<p>This creates a new directory "myrepo" containing a clone of Alice's\r
+repository. The clone is on an equal footing with the original\r
+project, posessing its own copy of the original project's history.</p>\r
+<p>Bob then makes some changes and commits them:</p>\r
<div class="listingblock">\r
<div class="content">\r
-<pre><tt>$ git-update-index --refresh</tt></pre>\r
+<pre><tt>(edit files)\r
+$ git commit -a\r
+(repeat as necessary)</tt></pre>\r
</div></div>\r
-<p>in the new repository to make sure that the index file is up-to-date.</p>\r
-</li>\r
-</ul>\r
-<p>Note that the second point is true even across machines. You can\r
-duplicate a remote git repository with <strong>any</strong> regular copy mechanism, be it\r
-<tt>scp</tt>, <tt>rsync</tt> or <tt>wget</tt>.</p>\r
-<p>When copying a remote repository, you'll want to at a minimum update the\r
-index cache when you do this, and especially with other peoples'\r
-repositories you often want to make sure that the index cache is in some\r
-known state (you don't know <strong>what</strong> they've done and not yet checked in),\r
-so usually you'll precede the <tt>git-update-index</tt> with a</p>\r
+<p>When he's ready, he tells Alice to pull changes from the repository\r
+at /home/bob/myrepo. She does this with:</p>\r
<div class="listingblock">\r
<div class="content">\r
-<pre><tt>$ git-read-tree --reset HEAD\r
-$ git-update-index --refresh</tt></pre>\r
+<pre><tt>$ cd /home/alice/project\r
+$ git pull /home/bob/myrepo</tt></pre>\r
</div></div>\r
-<p>which will force a total index re-build from the tree pointed to by <tt>HEAD</tt>.\r
-It resets the index contents to <tt>HEAD</tt>, and then the <tt>git-update-index</tt>\r
-makes sure to match up all index entries with the checked-out files.\r
-If the original repository had uncommitted changes in its\r
-working tree, <tt>git-update-index —refresh</tt> notices them and\r
-tells you they need to be updated.</p>\r
-<p>The above can also be written as simply</p>\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
+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
+<p>A more cautious Alice might wish to examine Bob's changes before\r
+pulling them. She can do this by creating a temporary branch just\r
+for the purpose of studying Bob's changes:</p>\r
<div class="listingblock">\r
<div class="content">\r
-<pre><tt>$ git reset</tt></pre>\r
+<pre><tt>$ git fetch /home/bob/myrepo master:bob-incoming</tt></pre>\r
</div></div>\r
-<p>and in fact a lot of the common git command combinations can be scripted\r
-with the <tt>git xyz</tt> interfaces. You can learn things by just looking\r
-at what the various git scripts do. For example, <tt>git reset</tt> is the\r
-above two lines implemented in <tt>git-reset</tt>, but some things like\r
-<tt>git status</tt> and <tt>git commit</tt> are slightly more complex scripts around\r
-the basic git commands.</p>\r
-<p>Many (most?) public remote repositories will not contain any of\r
-the checked out files or even an index file, and will <strong>only</strong> contain the\r
-actual core git files. Such a repository usually doesn't even have the\r
-<tt>.git</tt> subdirectory, but has all the git files directly in the\r
-repository.</p>\r
-<p>To create your own local live copy of such a "raw" git repository, you'd\r
-first create your own subdirectory for the project, and then copy the\r
-raw repository contents into the <tt>.git</tt> directory. For example, to\r
-create your own copy of the git repository, you'd do the following</p>\r
+<p>which fetches the changes from Bob's master branch into a new branch\r
+named bob-incoming. (Unlike git pull, git fetch just fetches a copy\r
+of Bob's line of development without doing any merging). Then</p>\r
<div class="listingblock">\r
<div class="content">\r
-<pre><tt>$ mkdir my-git\r
-$ cd my-git\r
-$ rsync -rL rsync://rsync.kernel.org/pub/scm/git/git.git/ .git</tt></pre>\r
+<pre><tt>$ git whatchanged -p master..bob-incoming</tt></pre>\r
</div></div>\r
-<p>followed by</p>\r
+<p>shows a list of all the changes that Bob made since he branched from\r
+Alice's master branch.</p>\r
+<p>After examing those changes, and possibly fixing things, Alice can\r
+pull the changes into her master branch:</p>\r
<div class="listingblock">\r
<div class="content">\r
-<pre><tt>$ git-read-tree HEAD</tt></pre>\r
+<pre><tt>$ git checkout master\r
+$ git pull . bob-incoming</tt></pre>\r
</div></div>\r
-<p>to populate the index. However, now you have populated the index, and\r
-you have all the git internal files, but you will notice that you don't\r
-actually have any of the working tree files to work on. To get\r
-those, you'd check them out with</p>\r
+<p>The last command is a pull from the "bob-incoming" branch in Alice's\r
+own repository.</p>\r
+<p>Later, Bob can update his repo with Alice's latest changes using</p>\r
<div class="listingblock">\r
<div class="content">\r
-<pre><tt>$ git-checkout-index -u -a</tt></pre>\r
+<pre><tt>$ git pull</tt></pre>\r
</div></div>\r
-<p>where the <tt>-u</tt> flag means that you want the checkout to keep the index\r
-up-to-date (so that you don't have to refresh it afterward), and the\r
-<tt>-a</tt> flag means "check out all files" (if you have a stale copy or an\r
-older version of a checked out tree you may also need to add the <tt>-f</tt>\r
-flag first, to tell git-checkout-index to <strong>force</strong> overwriting of any old\r
-files).</p>\r
-<p>Again, this can all be simplified with</p>\r
+<p>Note that he doesn't need to give the path to Alice's repository;\r
+when Bob cloned Alice's repository, git stored the location of her\r
+repository in the file .git/remotes/origin, and that location is used\r
+as the default for pulls.</p>\r
+<p>Bob may also notice a branch in his repository that he didn't create:</p>\r
<div class="listingblock">\r
<div class="content">\r
-<pre><tt>$ git clone rsync://rsync.kernel.org/pub/scm/git/git.git/ my-git\r
-$ cd my-git\r
-$ git checkout</tt></pre>\r
+<pre><tt>$ git branch\r
+* master\r
+ origin</tt></pre>\r
</div></div>\r
-<p>which will end up doing all of the above for you.</p>\r
-<p>You have now successfully copied somebody else's (mine) remote\r
-repository, and checked it out.</p>\r
-</div>\r
-<h2>Creating a new branch</h2>\r
-<div class="sectionbody">\r
-<p>Branches in git are really nothing more than pointers into the git\r
-object database from within the <tt>.git/refs/</tt> subdirectory, and as we\r
-already discussed, the <tt>HEAD</tt> branch is nothing but a symlink to one of\r
-these object pointers.</p>\r
-<p>You can at any time create a new branch by just picking an arbitrary\r
-point in the project history, and just writing the SHA1 name of that\r
-object into a file under <tt>.git/refs/heads/</tt>. You can use any filename you\r
-want (and indeed, subdirectories), but the convention is that the\r
-"normal" branch is called <tt>master</tt>. That's just a convention, though,\r
-and nothing enforces it.</p>\r
-<p>To show that as an example, let's go back to the git-tutorial repository we\r
-used earlier, and create a branch in it. You do that by simply just\r
-saying that you want to check out a new branch:</p>\r
-<div class="listingblock">\r
-<div class="content">\r
-<pre><tt>$ git checkout -b mybranch</tt></pre>\r
-</div></div>\r
-<p>will create a new branch based at the current <tt>HEAD</tt> position, and switch\r
+<p>The "origin" branch, which was created automatically by "git clone",\r
+is a pristine copy of Alice's master branch; Bob should never commit\r
to it.</p>\r
-<div class="admonitionblock">\r
-<table><tr>\r
-<td class="icon">\r
-<div class="title">Note</div>\r
-</td>\r
-<td class="content">\r
-<p>If you make the decision to start your new branch at some\r
-other point in the history than the current <tt>HEAD</tt>, you can do so by\r
-just telling <tt>git checkout</tt> what the base of the checkout would be.\r
-In other words, if you have an earlier tag or branch, you'd just do</p>\r
-<div class="listingblock">\r
-<div class="content">\r
-<pre><tt>$ git checkout -b mybranch earlier-commit</tt></pre>\r
-</div></div>\r
-<p>and it would create the new branch <tt>mybranch</tt> at the earlier commit,\r
-and check out the state at that time.</p>\r
-</td>\r
-</tr></table>\r
-</div>\r
-<p>You can always just jump back to your original <tt>master</tt> branch by doing</p>\r
+<p>If Bob later decides to work from a different host, he can still\r
+perform clones and pulls using the ssh protocol:</p>\r
<div class="listingblock">\r
<div class="content">\r
-<pre><tt>$ git checkout master</tt></pre>\r
+<pre><tt>$ git clone alice.org:/home/alice/project myrepo</tt></pre>\r
</div></div>\r
-<p>(or any other branch-name, for that matter) and if you forget which\r
-branch you happen to be on, a simple</p>\r
-<div class="listingblock">\r
-<div class="content">\r
-<pre><tt>$ ls -l .git/HEAD</tt></pre>\r
-</div></div>\r
-<p>will tell you where it's pointing (Note that on platforms with bad or no\r
-symlink support, you have to execute</p>\r
-<div class="listingblock">\r
-<div class="content">\r
-<pre><tt>$ cat .git/HEAD</tt></pre>\r
-</div></div>\r
-<p>instead). To get the list of branches you have, you can say</p>\r
-<div class="listingblock">\r
-<div class="content">\r
-<pre><tt>$ git branch</tt></pre>\r
-</div></div>\r
-<p>which is nothing more than a simple script around <tt>ls .git/refs/heads</tt>.\r
-There will be asterisk in front of the branch you are currently on.</p>\r
-<p>Sometimes you may wish to create a new branch _without_ actually\r
-checking it out and switching to it. If so, just use the command</p>\r
-<div class="listingblock">\r
-<div class="content">\r
-<pre><tt>$ git branch <branchname> [startingpoint]</tt></pre>\r
-</div></div>\r
-<p>which will simply _create_ the branch, but will not do anything further.\r
-You can then later — once you decide that you want to actually develop\r
-on that branch — switch to that branch with a regular <tt>git checkout</tt>\r
-with the branchname as the argument.</p>\r
-</div>\r
-<h2>Merging two branches</h2>\r
-<div class="sectionbody">\r
-<p>One of the ideas of having a branch is that you do some (possibly\r
-experimental) work in it, and eventually merge it back to the main\r
-branch. So assuming you created the above <tt>mybranch</tt> that started out\r
-being the same as the original <tt>master</tt> branch, let's make sure we're in\r
-that branch, and do some work there.</p>\r
-<div class="listingblock">\r
-<div class="content">\r
-<pre><tt>$ git checkout mybranch\r
-$ echo "Work, work, work" >>hello\r
-$ git commit -m 'Some work.' hello</tt></pre>\r
-</div></div>\r
-<p>Here, we just added another line to <tt>hello</tt>, and we used a shorthand for\r
-doing both <tt>git-update-index hello</tt> and <tt>git commit</tt> by just giving the\r
-filename directly to <tt>git commit</tt>. The <tt>-m</tt> flag is to give the\r
-commit log message from the command line.</p>\r
-<p>Now, to make it a bit more interesting, let's assume that somebody else\r
-does some work in the original branch, and simulate that by going back\r
-to the master branch, and editing the same file differently there:</p>\r
-<div class="listingblock">\r
-<div class="content">\r
-<pre><tt>$ git checkout master</tt></pre>\r
-</div></div>\r
-<p>Here, take a moment to look at the contents of <tt>hello</tt>, and notice how they\r
-don't contain the work we just did in <tt>mybranch</tt> — because that work\r
-hasn't happened in the <tt>master</tt> branch at all. Then do</p>\r
-<div class="listingblock">\r
-<div class="content">\r
-<pre><tt>$ echo "Play, play, play" >>hello\r
-$ echo "Lots of fun" >>example\r
-$ git commit -m 'Some fun.' hello example</tt></pre>\r
-</div></div>\r
-<p>since the master branch is obviously in a much better mood.</p>\r
-<p>Now, you've got two branches, and you decide that you want to merge the\r
-work done. Before we do that, let's introduce a cool graphical tool that\r
-helps you view what's going on:</p>\r
-<div class="listingblock">\r
-<div class="content">\r
-<pre><tt>$ gitk --all</tt></pre>\r
-</div></div>\r
-<p>will show you graphically both of your branches (that's what the <tt>--all</tt>\r
-means: normally it will just show you your current <tt>HEAD</tt>) and their\r
-histories. You can also see exactly how they came to be from a common\r
-source.</p>\r
-<p>Anyway, let's exit <tt>gitk</tt> (<tt>^Q</tt> or the File menu), and decide that we want\r
-to merge the work we did on the <tt>mybranch</tt> branch into the <tt>master</tt>\r
-branch (which is currently our <tt>HEAD</tt> too). To do that, there's a nice\r
-script called <tt>git merge</tt>, which wants to know which branches you want\r
-to resolve and what the merge is all about:</p>\r
-<div class="listingblock">\r
-<div class="content">\r
-<pre><tt>$ git merge "Merge work in mybranch" HEAD mybranch</tt></pre>\r
-</div></div>\r
-<p>where the first argument is going to be used as the commit message if\r
-the merge can be resolved automatically.</p>\r
-<p>Now, in this case we've intentionally created a situation where the\r
-merge will need to be fixed up by hand, though, so git will do as much\r
-of it as it can automatically (which in this case is just merge the <tt>example</tt>\r
-file, which had no differences in the <tt>mybranch</tt> branch), and say:</p>\r
-<div class="listingblock">\r
-<div class="content">\r
-<pre><tt> Trying really trivial in-index merge...\r
- fatal: Merge requires file-level merging\r
- Nope.\r
- ...\r
- Auto-merging hello\r
- CONFLICT (content): Merge conflict in hello\r
- Automatic merge failed/prevented; fix up by hand</tt></pre>\r
-</div></div>\r
-<p>which is way too verbose, but it basically tells you that it failed the\r
-really trivial merge ("Simple merge") and did an "Automatic merge"\r
-instead, but that too failed due to conflicts in <tt>hello</tt>.</p>\r
-<p>Not to worry. It left the (trivial) conflict in <tt>hello</tt> in the same form you\r
-should already be well used to if you've ever used CVS, so let's just\r
-open <tt>hello</tt> in our editor (whatever that may be), and fix it up somehow.\r
-I'd suggest just making it so that <tt>hello</tt> contains all four lines:</p>\r
-<div class="listingblock">\r
-<div class="content">\r
-<pre><tt>Hello World\r
-It's a new day for git\r
-Play, play, play\r
-Work, work, work</tt></pre>\r
-</div></div>\r
-<p>and once you're happy with your manual merge, just do a</p>\r
-<div class="listingblock">\r
-<div class="content">\r
-<pre><tt>$ git commit hello</tt></pre>\r
-</div></div>\r
-<p>which will very loudly warn you that you're now committing a merge\r
-(which is correct, so never mind), and you can write a small merge\r
-message about your adventures in git-merge-land.</p>\r
-<p>After you're done, start up <tt>gitk --all</tt> to see graphically what the\r
-history looks like. Notice that <tt>mybranch</tt> still exists, and you can\r
-switch to it, and continue to work with it if you want to. The\r
-<tt>mybranch</tt> branch will not contain the merge, but next time you merge it\r
-from the <tt>master</tt> branch, git will know how you merged it, so you'll not\r
-have to do _that_ merge again.</p>\r
-<p>Another useful tool, especially if you do not always work in X-Window\r
-environment, is <tt>git show-branch</tt>.</p>\r
-<div class="listingblock">\r
-<div class="content">\r
-<pre><tt>$ git show-branch master mybranch\r
-* [master] Merge work in mybranch\r
- ! [mybranch] Some work.\r
---\r
-- [master] Merge work in mybranch\r
-*+ [mybranch] Some work.</tt></pre>\r
-</div></div>\r
-<p>The first two lines indicate that it is showing the two branches\r
-and the first line of the commit log message from their\r
-top-of-the-tree commits, you are currently on <tt>master</tt> branch\r
-(notice the asterisk <tt><strong></tt> character), and the first column for\r
-the later output lines is used to show commits contained in the\r
-<tt>master</tt> branch, and the second column for the <tt>mybranch</tt>\r
-branch. Three commits are shown along with their log messages.\r
-All of them have non blank characters in the first column (<tt></strong></tt>\r
-shows an ordinary commit on the current branch, <tt>.</tt> is a merge commit), which\r
-means they are now part of the <tt>master</tt> branch. Only the "Some\r
-work" commit has the plus <tt>+</tt> character in the second column,\r
-because <tt>mybranch</tt> has not been merged to incorporate these\r
-commits from the master branch. The string inside brackets\r
-before the commit log message is a short name you can use to\r
-name the commit. In the above example, <em>master</em> and <em>mybranch</em>\r
-are branch heads. <em>master~1</em> is the first parent of <em>master</em>\r
-branch head. Please see <em>git-rev-parse</em> documentation if you\r
-see more complex cases.</p>\r
-<p>Now, let's pretend you are the one who did all the work in\r
-<tt>mybranch</tt>, and the fruit of your hard work has finally been merged\r
-to the <tt>master</tt> branch. Let's go back to <tt>mybranch</tt>, and run\r
-resolve to get the "upstream changes" back to your branch.</p>\r
-<div class="listingblock">\r
-<div class="content">\r
-<pre><tt>$ git checkout mybranch\r
-$ git merge "Merge upstream changes." HEAD master</tt></pre>\r
-</div></div>\r
-<p>This outputs something like this (the actual commit object names\r
-would be different)</p>\r
-<div class="listingblock">\r
-<div class="content">\r
-<pre><tt>Updating from ae3a2da... to a80b4aa....\r
- example | 1 +\r
- hello | 1 +\r
- 2 files changed, 2 insertions(+), 0 deletions(-)</tt></pre>\r
-</div></div>\r
-<p>Because your branch did not contain anything more than what are\r
-already merged into the <tt>master</tt> branch, the resolve operation did\r
-not actually do a merge. Instead, it just updated the top of\r
-the tree of your branch to that of the <tt>master</tt> branch. This is\r
-often called <em>fast forward</em> merge.</p>\r
-<p>You can run <tt>gitk --all</tt> again to see how the commit ancestry\r
-looks like, or run <tt>show-branch</tt>, which tells you this.</p>\r
-<div class="listingblock">\r
-<div class="content">\r
-<pre><tt>$ git show-branch master mybranch\r
-! [master] Merge work in mybranch\r
- * [mybranch] Merge work in mybranch\r
---\r
--- [master] Merge work in mybranch</tt></pre>\r
-</div></div>\r
-</div>\r
-<h2>Merging external work</h2>\r
-<div class="sectionbody">\r
-<p>It's usually much more common that you merge with somebody else than\r
-merging with your own branches, so it's worth pointing out that git\r
-makes that very easy too, and in fact, it's not that different from\r
-doing a <tt>git merge</tt>. In fact, a remote merge ends up being nothing\r
-more than "fetch the work from a remote repository into a temporary tag"\r
-followed by a <tt>git merge</tt>.</p>\r
-<p>Fetching from a remote repository is done by, unsurprisingly,\r
-<tt>git fetch</tt>:</p>\r
-<div class="listingblock">\r
-<div class="content">\r
-<pre><tt>$ git fetch <remote-repository></tt></pre>\r
-</div></div>\r
-<p>One of the following transports can be used to name the\r
-repository to download from:</p>\r
-<dl>\r
-<dt>\r
-Rsync\r
-</dt>\r
-<dd>\r
-<p>\r
- <tt>rsync://remote.machine/path/to/repo.git/</tt>\r
-</p>\r
-<p>Rsync transport is usable for both uploading and downloading,\r
-but is completely unaware of what git does, and can produce\r
-unexpected results when you download from the public repository\r
-while the repository owner is uploading into it via <tt>rsync</tt>\r
-transport. Most notably, it could update the files under\r
-<tt>refs/</tt> which holds the object name of the topmost commits\r
-before uploading the files in <tt>objects/</tt> — the downloader would\r
-obtain head commit object name while that object itself is still\r
-not available in the repository. For this reason, it is\r
-considered deprecated.</p>\r
-</dd>\r
-<dt>\r
-SSH\r
-</dt>\r
-<dd>\r
-<p>\r
- <tt>remote.machine:/path/to/repo.git/</tt> or\r
-</p>\r
-<p><tt>ssh://remote.machine/path/to/repo.git/</tt></p>\r
-<p>This transport can be used for both uploading and downloading,\r
-and requires you to have a log-in privilege over <tt>ssh</tt> to the\r
-remote machine. It finds out the set of objects the other side\r
-lacks by exchanging the head commits both ends have and\r
-transfers (close to) minimum set of objects. It is by far the\r
-most efficient way to exchange git objects between repositories.</p>\r
-</dd>\r
-<dt>\r
-Local directory\r
-</dt>\r
-<dd>\r
-<p>\r
- <tt>/path/to/repo.git/</tt>\r
-</p>\r
-<p>This transport is the same as SSH transport but uses <tt>sh</tt> to run\r
-both ends on the local machine instead of running other end on\r
-the remote machine via <tt>ssh</tt>.</p>\r
-</dd>\r
-<dt>\r
-git Native\r
-</dt>\r
-<dd>\r
-<p>\r
- <tt>git://remote.machine/path/to/repo.git/</tt>\r
-</p>\r
-<p>This transport was designed for anonymous downloading. Like SSH\r
-transport, it finds out the set of objects the downstream side\r
-lacks and transfers (close to) minimum set of objects.</p>\r
-</dd>\r
-<dt>\r
-HTTP(S)\r
-</dt>\r
-<dd>\r
-<p>\r
- <tt>http://remote.machine/path/to/repo.git/</tt>\r
-</p>\r
-<p>Downloader from http and https URL\r
-first obtains the topmost commit object name from the remote site\r
-by looking at the specified refname under <tt>repo.git/refs/</tt> directory,\r
-and then tries to obtain the\r
-commit object by downloading from <tt>repo.git/objects/xx/xxx...</tt>\r
-using the object name of that commit object. Then it reads the\r
-commit object to find out its parent commits and the associate\r
-tree object; it repeats this process until it gets all the\r
-necessary objects. Because of this behaviour, they are\r
-sometimes also called <em>commit walkers</em>.</p>\r
-<p>The <em>commit walkers</em> are sometimes also called <em>dumb\r
-transports</em>, because they do not require any git aware smart\r
-server like git Native transport does. Any stock HTTP server\r
-that does not even support directory index would suffice. But\r
-you must prepare your repository with <tt>git-update-server-info</tt>\r
-to help dumb transport downloaders.</p>\r
-<p>There are (confusingly enough) <tt>git-ssh-fetch</tt> and <tt>git-ssh-upload</tt>\r
-programs, which are <em>commit walkers</em>; they outlived their\r
-usefulness when git Native and SSH transports were introduced,\r
-and not used by <tt>git pull</tt> or <tt>git push</tt> scripts.</p>\r
-</dd>\r
-</dl>\r
-<p>Once you fetch from the remote repository, you <tt>resolve</tt> that\r
-with your current branch.</p>\r
-<p>However — it's such a common thing to <tt>fetch</tt> and then\r
-immediately <tt>resolve</tt>, that it's called <tt>git pull</tt>, and you can\r
-simply do</p>\r
-<div class="listingblock">\r
-<div class="content">\r
-<pre><tt>$ git pull <remote-repository></tt></pre>\r
-</div></div>\r
-<p>and optionally give a branch-name for the remote end as a second\r
-argument.</p>\r
-<div class="admonitionblock">\r
-<table><tr>\r
-<td class="icon">\r
-<div class="title">Note</div>\r
-</td>\r
-<td class="content">You could do without using any branches at all, by\r
-keeping as many local repositories as you would like to have\r
-branches, and merging between them with <tt>git pull</tt>, just like\r
-you merge between branches. The advantage of this approach is\r
-that it lets you keep set of files for each <tt>branch</tt> checked\r
-out and you may find it easier to switch back and forth if you\r
-juggle multiple lines of development simultaneously. Of\r
-course, you will pay the price of more disk usage to hold\r
-multiple working trees, but disk space is cheap these days.</td>\r
-</tr></table>\r
-</div>\r
-<div class="admonitionblock">\r
-<table><tr>\r
-<td class="icon">\r
-<div class="title">Note</div>\r
-</td>\r
-<td class="content">You could even pull from your own repository by\r
-giving <em>.</em> as <remote-repository> parameter to <tt>git pull</tt>. This\r
-is useful when you want to merge a local branch (or more, if you\r
-are making an Octopus) into the current branch.</td>\r
-</tr></table>\r
-</div>\r
-<p>It is likely that you will be pulling from the same remote\r
-repository from time to time. As a short hand, you can store\r
-the remote repository URL in a file under .git/remotes/\r
-directory, like this:</p>\r
-<div class="listingblock">\r
-<div class="content">\r
-<pre><tt>$ mkdir -p .git/remotes/\r
-$ cat >.git/remotes/linus <<\EOF\r
-URL: http://www.kernel.org/pub/scm/git/git.git/\r
-EOF</tt></pre>\r
-</div></div>\r
-<p>and use the filename to <tt>git pull</tt> instead of the full URL.\r
-The URL specified in such file can even be a prefix\r
-of a full URL, like this:</p>\r
-<div class="listingblock">\r
-<div class="content">\r
-<pre><tt>$ cat >.git/remotes/jgarzik <<\EOF\r
-URL: http://www.kernel.org/pub/scm/linux/git/jgarzik/\r
-EOF</tt></pre>\r
-</div></div>\r
-<p>Examples.</p>\r
-<ol>\r
-<li>\r
-<p>\r
-<tt>git pull linus</tt>\r
-</p>\r
-</li>\r
-<li>\r
-<p>\r
-<tt>git pull linus tag v0.99.1</tt>\r
-</p>\r
-</li>\r
-<li>\r
-<p>\r
-<tt>git pull jgarzik/netdev-2.6.git/ e100</tt>\r
-</p>\r
-</li>\r
-</ol>\r
-<p>the above are equivalent to:</p>\r
-<ol>\r
-<li>\r
-<p>\r
-<tt>git pull http://www.kernel.org/pub/scm/git/git.git/ HEAD</tt>\r
-</p>\r
-</li>\r
-<li>\r
-<p>\r
-<tt>git pull http://www.kernel.org/pub/scm/git/git.git/ tag v0.99.1</tt>\r
-</p>\r
-</li>\r
-<li>\r
-<p>\r
-<tt>git pull http://www.kernel.org/pub/…/jgarzik/netdev-2.6.git e100</tt>\r
-</p>\r
-</li>\r
-</ol>\r
+<p>Alternatively, git has a native protocol, or can use rsync or http;\r
+see <a href="git-pull.html">git-pull(1)</a> for details.</p>\r
+<p>Git can also be used in a CVS-like mode, with a central repository\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>How does the merge work?</h2>\r
+<h2>Keeping track of history</h2>\r
<div class="sectionbody">\r
-<p>We said this tutorial shows what plumbing does to help you cope\r
-with the porcelain that isn't flushing, but we so far did not\r
-talk about how the merge really works. If you are following\r
-this tutorial the first time, I'd suggest to skip to "Publishing\r
-your work" section and come back here later.</p>\r
-<p>OK, still with me? To give us an example to look at, let's go\r
-back to the earlier repository with "hello" and "example" file,\r
-and bring ourselves back to the pre-merge state:</p>\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
<div class="listingblock">\r
<div class="content">\r
-<pre><tt>$ git show-branch --more=3 master mybranch\r
-! [master] Merge work in mybranch\r
- * [mybranch] Merge work in mybranch\r
---\r
--- [master] Merge work in mybranch\r
-+* [master^2] Some work.\r
-+* [master^] Some fun.</tt></pre>\r
+<pre><tt>git diff HEAD^ HEAD</tt></pre>\r
</div></div>\r
-<p>Remember, before running <tt>git merge</tt>, our <tt>master</tt> head was at\r
-"Some fun." commit, while our <tt>mybranch</tt> head was at "Some\r
-work." commit.</p>\r
+<p>shows the difference between the most-recently checked-in state of\r
+the tree and the previous state, and</p>\r
<div class="listingblock">\r
<div class="content">\r
-<pre><tt>$ git checkout mybranch\r
-$ git reset --hard master^2\r
-$ git checkout master\r
-$ git reset --hard master^</tt></pre>\r
+<pre><tt>git diff HEAD^^ HEAD^</tt></pre>\r
</div></div>\r
-<p>After rewinding, the commit structure should look like this:</p>\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<sup>^</sup>^^,\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
<div class="listingblock">\r
<div class="content">\r
-<pre><tt>$ git show-branch\r
-* [master] Some fun.\r
- ! [mybranch] Some work.\r
---\r
- + [mybranch] Some work.\r
-* [master] Some fun.\r
-*+ [mybranch^] New day.</tt></pre>\r
+<pre><tt>git diff HEAD experimental</tt></pre>\r
</div></div>\r
-<p>Now we are ready to experiment with the merge by hand.</p>\r
-<p><tt>git merge</tt> command, when merging two branches, uses 3-way merge\r
-algorithm. First, it finds the common ancestor between them.\r
-The command it uses is <tt>git-merge-base</tt>:</p>\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
<div class="listingblock">\r
<div class="content">\r
-<pre><tt>$ mb=$(git-merge-base HEAD mybranch)</tt></pre>\r
+<pre><tt>git whatchanged HEAD..experimental</tt></pre>\r
</div></div>\r
-<p>The command writes the commit object name of the common ancestor\r
-to the standard output, so we captured its output to a variable,\r
-because we will be using it in the next step. BTW, the common\r
-ancestor commit is the "New day." commit in this case. You can\r
-tell it by:</p>\r
+<p>will do that, just as</p>\r
<div class="listingblock">\r
<div class="content">\r
-<pre><tt>$ git-name-rev $mb\r
-my-first-tag</tt></pre>\r
+<pre><tt>git whatchanged experimental..HEAD</tt></pre>\r
</div></div>\r
-<p>After finding out a common ancestor commit, the second step is\r
-this:</p>\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
<div class="listingblock">\r
<div class="content">\r
-<pre><tt>$ git-read-tree -m -u $mb HEAD mybranch</tt></pre>\r
+<pre><tt>$ git-tag v2.5 HEAD^^</tt></pre>\r
</div></div>\r
-<p>This is the same <tt>git-read-tree</tt> command we have already seen,\r
-but it takes three trees, unlike previous examples. This reads\r
-the contents of each tree into different <em>stage</em> in the index\r
-file (the first tree goes to stage 1, the second stage 2,\r
-etc.). After reading three trees into three stages, the paths\r
-that are the same in all three stages are <em>collapsed</em> into stage\r
-0. Also paths that are the same in two of three stages are\r
-collapsed into stage 0, taking the SHA1 from either stage 2 or\r
-stage 3, whichever is different from stage 1 (i.e. only one side\r
-changed from the common ancestor).</p>\r
-<p>After <em>collapsing</em> operation, paths that are different in three\r
-trees are left in non-zero stages. At this point, you can\r
-inspect the index file with this command:</p>\r
-<div class="listingblock">\r
-<div class="content">\r
-<pre><tt>$ git-ls-files --stage\r
-100644 7f8b141b65fdcee47321e399a2598a235a032422 0 example\r
-100644 263414f423d0e4d70dae8fe53fa34614ff3e2860 1 hello\r
-100644 06fa6a24256dc7e560efa5687fa84b51f0263c3a 2 hello\r
-100644 cc44c73eb783565da5831b4d820c962954019b69 3 hello</tt></pre>\r
-</div></div>\r
-<p>In our example of only two files, we did not have unchanged\r
-files so only <em>example</em> resulted in collapsing, but in real-life\r
-large projects, only small number of files change in one commit,\r
-and this <em>collapsing</em> tends to trivially merge most of the paths\r
-fairly quickly, leaving only a handful the real changes in non-zero\r
-stages.</p>\r
-<p>To look at only non-zero stages, use <tt>--unmerged</tt> flag:</p>\r
-<div class="listingblock">\r
-<div class="content">\r
-<pre><tt>$ git-ls-files --unmerged\r
-100644 263414f423d0e4d70dae8fe53fa34614ff3e2860 1 hello\r
-100644 06fa6a24256dc7e560efa5687fa84b51f0263c3a 2 hello\r
-100644 cc44c73eb783565da5831b4d820c962954019b69 3 hello</tt></pre>\r
-</div></div>\r
-<p>The next step of merging is to merge these three versions of the\r
-file, using 3-way merge. This is done by giving\r
-<tt>git-merge-one-file</tt> command as one of the arguments to\r
-<tt>git-merge-index</tt> command:</p>\r
-<div class="listingblock">\r
-<div class="content">\r
-<pre><tt>$ git-merge-index git-merge-one-file hello\r
-Auto-merging hello.\r
-merge: warning: conflicts during merge\r
-ERROR: Merge conflict in hello.\r
-fatal: merge program failed</tt></pre>\r
-</div></div>\r
-<p><tt>git-merge-one-file</tt> script is called with parameters to\r
-describe those three versions, and is responsible to leave the\r
-merge results in the working tree.\r
-It is a fairly straightforward shell script, and\r
-eventually calls <tt>merge</tt> program from RCS suite to perform a\r
-file-level 3-way merge. In this case, <tt>merge</tt> detects\r
-conflicts, and the merge result with conflict marks is left in\r
-the working tree.. This can be seen if you run <tt>ls-files\r
-—stage</tt> again at this point:</p>\r
-<div class="listingblock">\r
-<div class="content">\r
-<pre><tt>$ git-ls-files --stage\r
-100644 7f8b141b65fdcee47321e399a2598a235a032422 0 example\r
-100644 263414f423d0e4d70dae8fe53fa34614ff3e2860 1 hello\r
-100644 06fa6a24256dc7e560efa5687fa84b51f0263c3a 2 hello\r
-100644 cc44c73eb783565da5831b4d820c962954019b69 3 hello</tt></pre>\r
-</div></div>\r
-<p>This is the state of the index file and the working file after\r
-<tt>git merge</tt> returns control back to you, leaving the conflicting\r
-merge for you to resolve. Notice that the path <tt>hello</tt> is still\r
-unmerged, and what you see with <tt>git diff</tt> at this point is\r
-differences since stage 2 (i.e. your version).</p>\r
-</div>\r
-<h2>Publishing your work</h2>\r
-<div class="sectionbody">\r
-<p>So we can use somebody else's work from a remote repository; but\r
-how can <strong>you</strong> prepare a repository to let other people pull from\r
-it?</p>\r
-<p>Your do your real work in your working tree that has your\r
-primary repository hanging under it as its <tt>.git</tt> subdirectory.\r
-You <strong>could</strong> make that repository accessible remotely and ask\r
-people to pull from it, but in practice that is not the way\r
-things are usually done. A recommended way is to have a public\r
-repository, make it reachable by other people, and when the\r
-changes you made in your primary working tree are in good shape,\r
-update the public repository from it. This is often called\r
-<em>pushing</em>.</p>\r
-<div class="admonitionblock">\r
-<table><tr>\r
-<td class="icon">\r
-<div class="title">Note</div>\r
-</td>\r
-<td class="content">This public repository could further be mirrored, and that is\r
-how git repositories at <tt>kernel.org</tt> are managed.</td>\r
-</tr></table>\r
-</div>\r
-<p>Publishing the changes from your local (private) repository to\r
-your remote (public) repository requires a write privilege on\r
-the remote machine. You need to have an SSH account there to\r
-run a single command, <tt>git-receive-pack</tt>.</p>\r
-<p>First, you need to create an empty repository on the remote\r
-machine that will house your public repository. This empty\r
-repository will be populated and be kept up-to-date by pushing\r
-into it later. Obviously, this repository creation needs to be\r
-done only once.</p>\r
-<div class="admonitionblock">\r
-<table><tr>\r
-<td class="icon">\r
-<div class="title">Note</div>\r
-</td>\r
-<td class="content"><tt>git push</tt> uses a pair of programs,\r
-<tt>git-send-pack</tt> on your local machine, and <tt>git-receive-pack</tt>\r
-on the remote machine. The communication between the two over\r
-the network internally uses an SSH connection.</td>\r
-</tr></table>\r
-</div>\r
-<p>Your private repository's git directory is usually <tt>.git</tt>, but\r
-your public repository is often named after the project name,\r
-i.e. <tt><project>.git</tt>. Let's create such a public repository for\r
-project <tt>my-git</tt>. After logging into the remote machine, create\r
-an empty directory:</p>\r
-<div class="listingblock">\r
-<div class="content">\r
-<pre><tt>$ mkdir my-git.git</tt></pre>\r
-</div></div>\r
-<p>Then, make that directory into a git repository by running\r
-<tt>git init-db</tt>, but this time, since its name is not the usual\r
-<tt>.git</tt>, we do things slightly differently:</p>\r
-<div class="listingblock">\r
-<div class="content">\r
-<pre><tt>$ GIT_DIR=my-git.git git-init-db</tt></pre>\r
-</div></div>\r
-<p>Make sure this directory is available for others you want your\r
-changes to be pulled by via the transport of your choice. Also\r
-you need to make sure that you have the <tt>git-receive-pack</tt>\r
-program on the <tt>$PATH</tt>.</p>\r
-<div class="admonitionblock">\r
-<table><tr>\r
-<td class="icon">\r
-<div class="title">Note</div>\r
-</td>\r
-<td class="content">Many installations of sshd do not invoke your shell as the login\r
-shell when you directly run programs; what this means is that if\r
-your login shell is <tt>bash</tt>, only <tt>.bashrc</tt> is read and not\r
-<tt>.bash_profile</tt>. As a workaround, make sure <tt>.bashrc</tt> sets up\r
-<tt>$PATH</tt> so that you can run <tt>git-receive-pack</tt> program.</td>\r
-</tr></table>\r
-</div>\r
-<div class="admonitionblock">\r
-<table><tr>\r
-<td class="icon">\r
-<div class="title">Note</div>\r
-</td>\r
-<td class="content">If you plan to publish this repository to be accessed over http,\r
-you should do <tt>chmod +x my-git.git/hooks/post-update</tt> at this\r
-point. This makes sure that every time you push into this\r
-repository, <tt>git-update-server-info</tt> is run.</td>\r
-</tr></table>\r
-</div>\r
-<p>Your "public repository" is now ready to accept your changes.\r
-Come back to the machine you have your private repository. From\r
-there, run this command:</p>\r
-<div class="listingblock">\r
-<div class="content">\r
-<pre><tt>$ git push <public-host>:/path/to/my-git.git master</tt></pre>\r
-</div></div>\r
-<p>This synchronizes your public repository to match the named\r
-branch head (i.e. <tt>master</tt> in this case) and objects reachable\r
-from them in your current repository.</p>\r
-<p>As a real example, this is how I update my public git\r
-repository. Kernel.org mirror network takes care of the\r
-propagation to other publicly visible machines:</p>\r
-<div class="listingblock">\r
-<div class="content">\r
-<pre><tt>$ git push master.kernel.org:/pub/scm/git/git.git/</tt></pre>\r
-</div></div>\r
-</div>\r
-<h2>Packing your repository</h2>\r
-<div class="sectionbody">\r
-<p>Earlier, we saw that one file under <tt>.git/objects/??/</tt> directory\r
-is stored for each git object you create. This representation\r
-is efficient to create atomically and safely, but\r
-not so convenient to transport over the network. Since git objects are\r
-immutable once they are created, there is a way to optimize the\r
-storage by "packing them together". The command</p>\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
+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
<div class="listingblock">\r
<div class="content">\r
-<pre><tt>$ git repack</tt></pre>\r
+<pre><tt>$ git branch stable-release v2.5</tt></pre>\r
</div></div>\r
-<p>will do it for you. If you followed the tutorial examples, you\r
-would have accumulated about 17 objects in <tt>.git/objects/??/</tt>\r
-directories by now. <tt>git repack</tt> tells you how many objects it\r
-packed, and stores the packed file in <tt>.git/objects/pack</tt>\r
-directory.</p>\r
-<div class="admonitionblock">\r
-<table><tr>\r
-<td class="icon">\r
-<div class="title">Note</div>\r
-</td>\r
-<td class="content">You will see two files, <tt>pack-*.pack</tt> and <tt>pack-*.idx</tt>,\r
-in <tt>.git/objects/pack</tt> directory. They are closely related to\r
-each other, and if you ever copy them by hand to a different\r
-repository for whatever reason, you should make sure you copy\r
-them together. The former holds all the data from the objects\r
-in the pack, and the latter holds the index for random\r
-access.</td>\r
-</tr></table>\r
-</div>\r
-<p>If you are paranoid, running <tt>git-verify-pack</tt> command would\r
-detect if you have a corrupt pack, but do not worry too much.\r
-Our programs are always perfect ;-).</p>\r
-<p>Once you have packed objects, you do not need to leave the\r
-unpacked objects that are contained in the pack file anymore.</p>\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
<div class="listingblock">\r
<div class="content">\r
-<pre><tt>$ git prune-packed</tt></pre>\r
+<pre><tt>$ git reset --hard v2.5</tt></pre>\r
</div></div>\r
-<p>would remove them for you.</p>\r
-<p>You can try running <tt>find .git/objects -type f</tt> before and after\r
-you run <tt>git prune-packed</tt> if you are curious. Also <tt>git\r
-count-objects</tt> would tell you how many unpacked objects are in\r
-your repository and how much space they are consuming.</p>\r
-<div class="admonitionblock">\r
-<table><tr>\r
-<td class="icon">\r
-<div class="title">Note</div>\r
-</td>\r
-<td class="content"><tt>git pull</tt> is slightly cumbersome for HTTP transport, as a\r
-packed repository may contain relatively few objects in a\r
-relatively large pack. If you expect many HTTP pulls from your\r
-public repository you might want to repack & prune often, or\r
-never.</td>\r
-</tr></table>\r
-</div>\r
-<p>If you run <tt>git repack</tt> again at this point, it will say\r
-"Nothing to pack". Once you continue your development and\r
-accumulate the changes, running <tt>git repack</tt> again will create a\r
-new pack, that contains objects created since you packed your\r
-repository the last time. We recommend that you pack your project\r
-soon after the initial import (unless you are starting your\r
-project from scratch), and then run <tt>git repack</tt> every once in a\r
-while, depending on how active your project is.</p>\r
-<p>When a repository is synchronized via <tt>git push</tt> and <tt>git pull</tt>\r
-objects packed in the source repository are usually stored\r
-unpacked in the destination, unless rsync transport is used.\r
-While this allows you to use different packing strategies on\r
-both ends, it also means you may need to repack both\r
-repositories every once in a while.</p>\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>Working with Others</h2>\r
+<h2>Next Steps</h2>\r
<div class="sectionbody">\r
-<p>Although git is a truly distributed system, it is often\r
-convenient to organize your project with an informal hierarchy\r
-of developers. Linux kernel development is run this way. There\r
-is a nice illustration (page 17, "Merges to Mainline") in Randy\r
-Dunlap's presentation (<tt>http://tinyurl.com/a2jdg</tt>).</p>\r
-<p>It should be stressed that this hierarchy is purely <strong>informal</strong>.\r
-There is nothing fundamental in git that enforces the "chain of\r
-patch flow" this hierarchy implies. You do not have to pull\r
-from only one remote repository.</p>\r
-<p>A recommended workflow for a "project lead" goes like this:</p>\r
-<ol>\r
-<li>\r
-<p>\r
-Prepare your primary repository on your local machine. Your\r
- work is done there.\r
-</p>\r
-</li>\r
-<li>\r
-<p>\r
-Prepare a public repository accessible to others.\r
-</p>\r
-<p>If other people are pulling from your repository over dumb\r
-transport protocols (HTTP), you need to keep this repository\r
-<em>dumb transport friendly</em>. After <tt>git init-db</tt>,\r
-<tt>$GIT_DIR/hooks/post-update</tt> copied from the standard templates\r
-would contain a call to <tt>git-update-server-info</tt> but the\r
-<tt>post-update</tt> hook itself is disabled by default — enable it\r
-with <tt>chmod +x post-update</tt>. This makes sure <tt>git-update-server-info</tt>\r
-keeps the necessary files up-to-date.</p>\r
-</li>\r
-<li>\r
-<p>\r
-Push into the public repository from your primary\r
- repository.\r
-</p>\r
-</li>\r
-<li>\r
-<p>\r
-<tt>git repack</tt> the public repository. This establishes a big\r
- pack that contains the initial set of objects as the\r
- baseline, and possibly <tt>git prune</tt> if the transport\r
- used for pulling from your repository supports packed\r
- repositories.\r
-</p>\r
-</li>\r
-<li>\r
-<p>\r
-Keep working in your primary repository. Your changes\r
- include modifications of your own, patches you receive via\r
- e-mails, and merges resulting from pulling the "public"\r
- repositories of your "subsystem maintainers".\r
-</p>\r
-<p>You can repack this private repository whenever you feel like.</p>\r
-</li>\r
-<li>\r
-<p>\r
-Push your changes to the public repository, and announce it\r
- to the public.\r
-</p>\r
-</li>\r
-<li>\r
-<p>\r
-Every once in a while, "git repack" the public repository.\r
- Go back to step 5. and continue working.\r
-</p>\r
-</li>\r
-</ol>\r
-<p>A recommended work cycle for a "subsystem maintainer" who works\r
-on that project and has an own "public repository" goes like this:</p>\r
-<ol>\r
-<li>\r
-<p>\r
-Prepare your work repository, by <tt>git clone</tt> the public\r
- repository of the "project lead". The URL used for the\r
- initial cloning is stored in <tt>.git/remotes/origin</tt>.\r
-</p>\r
-</li>\r
-<li>\r
-<p>\r
-Prepare a public repository accessible to others, just like\r
- the "project lead" person does.\r
-</p>\r
-</li>\r
-<li>\r
-<p>\r
-Copy over the packed files from "project lead" public\r
- repository to your public repository, unless the "project\r
- lead" repository lives on the same machine as yours. In the\r
- latter case, you can use <tt>objects/info/alternates</tt> file to\r
- point at the repository you are borrowing from.\r
-</p>\r
-</li>\r
-<li>\r
-<p>\r
-Push into the public repository from your primary\r
- repository. Run <tt>git repack</tt>, and possibly <tt>git prune</tt> if the\r
- transport used for pulling from your repository supports\r
- packed repositories.\r
-</p>\r
-</li>\r
-<li>\r
-<p>\r
-Keep working in your primary repository. Your changes\r
- include modifications of your own, patches you receive via\r
- e-mails, and merges resulting from pulling the "public"\r
- repositories of your "project lead" and possibly your\r
- "sub-subsystem maintainers".\r
-</p>\r
-<p>You can repack this private repository whenever you feel\r
-like.</p>\r
-</li>\r
-<li>\r
-<p>\r
-Push your changes to your public repository, and ask your\r
- "project lead" and possibly your "sub-subsystem\r
- maintainers" to pull from it.\r
-</p>\r
-</li>\r
-<li>\r
-<p>\r
-Every once in a while, <tt>git repack</tt> the public repository.\r
- Go back to step 5. and continue working.\r
-</p>\r
-</li>\r
-</ol>\r
-<p>A recommended work cycle for an "individual developer" who does\r
-not have a "public" repository is somewhat different. It goes\r
-like this:</p>\r
-<ol>\r
-<li>\r
-<p>\r
-Prepare your work repository, by <tt>git clone</tt> the public\r
- repository of the "project lead" (or a "subsystem\r
- maintainer", if you work on a subsystem). The URL used for\r
- the initial cloning is stored in <tt>.git/remotes/origin</tt>.\r
-</p>\r
-</li>\r
-<li>\r
-<p>\r
-Do your work in your repository on <em>master</em> branch.\r
-</p>\r
-</li>\r
-<li>\r
-<p>\r
-Run <tt>git fetch origin</tt> from the public repository of your\r
- upstream every once in a while. This does only the first\r
- half of <tt>git pull</tt> but does not merge. The head of the\r
- public repository is stored in <tt>.git/refs/heads/origin</tt>.\r
-</p>\r
-</li>\r
-<li>\r
-<p>\r
-Use <tt>git cherry origin</tt> to see which ones of your patches\r
- were accepted, and/or use <tt>git rebase origin</tt> to port your\r
- unmerged changes forward to the updated upstream.\r
-</p>\r
-</li>\r
-<li>\r
-<p>\r
-Use <tt>git format-patch origin</tt> to prepare patches for e-mail\r
- submission to your upstream and send it out. Go back to\r
- step 2. and continue.\r
-</p>\r
-</li>\r
-</ol>\r
-</div>\r
-<h2>Working with Others, Shared Repository Style</h2>\r
-<div class="sectionbody">\r
-<p>If you are coming from CVS background, the style of cooperation\r
-suggested in the previous section may be new to you. You do not\r
-have to worry. git supports "shared public repository" style of\r
-cooperation you are probably more familiar with as well.</p>\r
-<p>For this, set up a public repository on a machine that is\r
-reachable via SSH by people with "commit privileges". Put the\r
-committers in the same user group and make the repository\r
-writable by that group. Make sure their umasks are set up to\r
-allow group members to write into directories other members\r
-have created.</p>\r
-<p>You, as an individual committer, then:</p>\r
+<p>Some good commands to explore next:</p>\r
<ul>\r
<li>\r
<p>\r
-First clone the shared repository to a local repository:\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
</p>\r
</li>\r
-</ul>\r
-<div class="listingblock">\r
-<div class="content">\r
-<pre><tt>$ git clone repo.shared.xz:/pub/scm/project.git/ my-project\r
-$ cd my-project\r
-$ hack away</tt></pre>\r
-</div></div>\r
-<ul>\r
<li>\r
<p>\r
-Merge the work others might have done while you were hacking\r
- away:\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
+ on emailed patches.\r
</p>\r
</li>\r
-</ul>\r
-<div class="listingblock">\r
-<div class="content">\r
-<pre><tt>$ git pull origin\r
-$ test the merge result</tt></pre>\r
-</div></div>\r
-<div class="admonitionblock">\r
-<table><tr>\r
-<td class="icon">\r
-<div class="title">Note</div>\r
-</td>\r
-<td class="content">\r
-<p>The first <tt>git clone</tt> would have placed the following in\r
-<tt>my-project/.git/remotes/origin</tt> file, and that's why this and\r
-the next step work.</p>\r
-<div class="listingblock">\r
-<div class="content">\r
-<pre><tt>URL: repo.shared.xz:/pub/scm/project.git/ my-project\r
-Pull: master:origin</tt></pre>\r
-</div></div>\r
-</td>\r
-</tr></table>\r
-</div>\r
-<ul>\r
<li>\r
<p>\r
-push your work as the new head of the shared\r
- repository.\r
+<a href="git-bisect.html">git-bisect(1)</a>: When there is a regression in your\r
+ project, one way to track down the bug is by searching through\r
+ the history to find the exact commit that's to blame. Git bisect\r
+ can help you perform a binary search for that commit. It is\r
+ smart enough to perform a close-to-optimal search even in the\r
+ case of complex non-linear history with lots of merged branches.\r
</p>\r
</li>\r
</ul>\r
-<div class="listingblock">\r
-<div class="content">\r
-<pre><tt>$ git push origin master</tt></pre>\r
-</div></div>\r
-<p>If somebody else pushed into the same shared repository while\r
-you were working locally, <tt>git push</tt> in the last step would\r
-complain, telling you that the remote <tt>master</tt> head does not\r
-fast forward. You need to pull and merge those other changes\r
-back before you push your work when it happens.</p>\r
-</div>\r
-<h2>Advanced Shared Repository Management</h2>\r
-<div class="sectionbody">\r
-<p>Being able to push into a shared repository means being able to\r
-write into it. If your developers are coming over the network,\r
-this means you, as the repository administrator, need to give\r
-each of them an SSH access to the shared repository machine.</p>\r
-<p>In some cases, though, you may not want to give a normal shell\r
-account to them, but want to restrict them to be able to only\r
-do <tt>git push</tt> into the repository and nothing else.</p>\r
-<p>You can achieve this by setting the login shell of your\r
-developers on the shared repository host to <tt>git-shell</tt> program.</p>\r
-<div class="admonitionblock">\r
-<table><tr>\r
-<td class="icon">\r
-<div class="title">Note</div>\r
-</td>\r
-<td class="content">Most likely you would also need to list <tt>git-shell</tt> program in\r
-<tt>/etc/shells</tt> file.</td>\r
-</tr></table>\r
-</div>\r
-<p>This restricts the set of commands that can be run from incoming\r
-SSH connection for these users to only <tt>receive-pack</tt> and\r
-<tt>upload-pack</tt>, so the only thing they can do are <tt>git fetch</tt> and\r
-<tt>git push</tt>.</p>\r
-<p>You still need to create UNIX user accounts for each developer,\r
-and put them in the same group. Make sure that the repository\r
-shared among these developers is writable by that group.</p>\r
-<ol>\r
-<li>\r
-<p>\r
-Initializing the shared repository with <tt>git-init-db —shared</tt>\r
-helps somewhat.\r
-</p>\r
-</li>\r
-<li>\r
-<p>\r
-Run the following in the shared repository:\r
-</p>\r
-<div class="listingblock">\r
-<div class="content">\r
-<pre><tt>$ chgrp -R $group repo.git\r
-$ find repo.git -type d -print | xargs chmod ug+rwx,g+s\r
-$ GIT_DIR=repo.git git repo-config core.sharedrepository true</tt></pre>\r
-</div></div>\r
-</li>\r
-</ol>\r
-<p>The above measures make sure that directories lazily created in\r
-<tt>$GIT_DIR</tt> are writable by group members. You, as the\r
-repository administrator, are still responsible to make sure\r
-your developers belong to that shared repository group and set\r
-their umask to a value no stricter than 027 (i.e. at least allow\r
-reading and searching by group members).</p>\r
-<p>You can implement finer grained branch policies using update\r
-hooks. There is a document ("control access to branches") in\r
-Documentation/howto by Carl Baldwin and JC outlining how to (1)\r
-limit access to branch per user, (2) forbid overwriting existing\r
-tags.</p>\r
-</div>\r
-<h2>Bundling your work together</h2>\r
-<div class="sectionbody">\r
-<p>It is likely that you will be working on more than one thing at\r
-a time. It is easy to manage those more-or-less independent tasks\r
-using branches with git.</p>\r
-<p>We have already seen how branches work previously,\r
-with "fun and work" example using two branches. The idea is the\r
-same if there are more than two branches. Let's say you started\r
-out from "master" head, and have some new code in the "master"\r
-branch, and two independent fixes in the "commit-fix" and\r
-"diff-fix" branches:</p>\r
-<div class="listingblock">\r
-<div class="content">\r
-<pre><tt>$ git show-branch\r
-! [commit-fix] Fix commit message normalization.\r
- ! [diff-fix] Fix rename detection.\r
- * [master] Release candidate #1\r
----\r
- + [diff-fix] Fix rename detection.\r
- + [diff-fix~1] Better common substring algorithm.\r
-+ [commit-fix] Fix commit message normalization.\r
- * [master] Release candidate #1\r
-++* [diff-fix~2] Pretty-print messages.</tt></pre>\r
-</div></div>\r
-<p>Both fixes are tested well, and at this point, you want to merge\r
-in both of them. You could merge in <em>diff-fix</em> first and then\r
-<em>commit-fix</em> next, like this:</p>\r
-<div class="listingblock">\r
-<div class="content">\r
-<pre><tt>$ git merge 'Merge fix in diff-fix' master diff-fix\r
-$ git merge 'Merge fix in commit-fix' master commit-fix</tt></pre>\r
-</div></div>\r
-<p>Which would result in:</p>\r
-<div class="listingblock">\r
-<div class="content">\r
-<pre><tt>$ git show-branch\r
-! [commit-fix] Fix commit message normalization.\r
- ! [diff-fix] Fix rename detection.\r
- * [master] Merge fix in commit-fix\r
----\r
- - [master] Merge fix in commit-fix\r
-+ * [commit-fix] Fix commit message normalization.\r
- - [master~1] Merge fix in diff-fix\r
- +* [diff-fix] Fix rename detection.\r
- +* [diff-fix~1] Better common substring algorithm.\r
- * [master~2] Release candidate #1\r
-++* [master~3] Pretty-print messages.</tt></pre>\r
-</div></div>\r
-<p>However, there is no particular reason to merge in one branch\r
-first and the other next, when what you have are a set of truly\r
-independent changes (if the order mattered, then they are not\r
-independent by definition). You could instead merge those two\r
-branches into the current branch at once. First let's undo what\r
-we just did and start over. We would want to get the master\r
-branch before these two merges by resetting it to <em>master~2</em>:</p>\r
-<div class="listingblock">\r
-<div class="content">\r
-<pre><tt>$ git reset --hard master~2</tt></pre>\r
-</div></div>\r
-<p>You can make sure <em>git show-branch</em> matches the state before\r
-those two <em>git merge</em> you just did. Then, instead of running\r
-two <em>git merge</em> commands in a row, you would pull these two\r
-branch heads (this is known as <em>making an Octopus</em>):</p>\r
-<div class="listingblock">\r
-<div class="content">\r
-<pre><tt>$ git pull . commit-fix diff-fix\r
-$ git show-branch\r
-! [commit-fix] Fix commit message normalization.\r
- ! [diff-fix] Fix rename detection.\r
- * [master] Octopus merge of branches 'diff-fix' and 'commit-fix'\r
----\r
- - [master] Octopus merge of branches 'diff-fix' and 'commit-fix'\r
-+ * [commit-fix] Fix commit message normalization.\r
- +* [diff-fix] Fix rename detection.\r
- +* [diff-fix~1] Better common substring algorithm.\r
- * [master~1] Release candidate #1\r
-++* [master~2] Pretty-print messages.</tt></pre>\r
-</div></div>\r
-<p>Note that you should not do Octopus because you can. An octopus\r
-is a valid thing to do and often makes it easier to view the\r
-commit history if you are pulling more than two independent\r
-changes at the same time. However, if you have merge conflicts\r
-with any of the branches you are merging in and need to hand\r
-resolve, that is an indication that the development happened in\r
-those branches were not independent after all, and you should\r
-merge two at a time, documenting how you resolved the conflicts,\r
-and the reason why you preferred changes made in one side over\r
-the other. Otherwise it would make the project history harder\r
-to follow, not easier.</p>\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 15-Jan-2006 02:13:30 PDT\r
+Last updated 22-Jan-2006 23:54:22 PDT\r
</div>\r
</div>\r
</body>\r
-A short git tutorial
-====================
+A tutorial introduction to git
+==============================
-Introduction
-------------
+This tutorial explains how to import a new project into git, make
+changes to it, and share changes with other developers.
-This is trying to be a short tutorial on setting up and using a git
-repository, mainly because being hands-on and using explicit examples is
-often the best way of explaining what is going on.
+First, note that you can get documentation for a command such as "git
+diff" with:
-In normal life, most people wouldn't use the "core" git programs
-directly, but rather script around them to make them more palatable.
-Understanding the core git stuff may help some people get those scripts
-done, though, and it may also be instructive in helping people
-understand what it is that the higher-level helper scripts are actually
-doing.
-
-The core git is often called "plumbing", with the prettier user
-interfaces on top of it called "porcelain". You may not want to use the
-plumbing directly very often, but it can be good to know what the
-plumbing does for when the porcelain isn't flushing.
-
-The material presented here often goes deep describing how things
-work internally. If you are mostly interested in using git as a
-SCM, you can skip them during your first pass.
-
-[NOTE]
-And those "too deep" descriptions are often marked as Note.
-
-[NOTE]
-If you are already familiar with another version control system,
-like CVS, you may want to take a look at
-link:everyday.html[Everyday GIT in 20 commands or so] first
-before reading this.
-
-
-Creating a git repository
--------------------------
+------------------------------------------------
+$ man git-diff
+------------------------------------------------
-Creating a new git repository couldn't be easier: all git repositories start
-out empty, and the only thing you need to do is find yourself a
-subdirectory that you want to use as a working tree - either an empty
-one for a totally new project, or an existing working tree that you want
-to import into git.
+Importing a new project
+-----------------------
-For our first example, we're going to start a totally new repository from
-scratch, with no pre-existing files, and we'll call it `git-tutorial`.
-To start up, create a subdirectory for it, change into that
-subdirectory, and initialize the git infrastructure with `git-init-db`:
+Assume you have a tarball project.tar.gz with your initial work. You
+can place it under git revision control as follows.
------------------------------------------------
-$ mkdir git-tutorial
-$ cd git-tutorial
-$ git-init-db
+$ tar xzf project.tar.gz
+$ cd project
+$ git init-db
------------------------------------------------
-to which git will reply
+Git will reply
-----------------
+------------------------------------------------
defaulting to local storage area
-----------------
-
-which is just git's way of saying that you haven't been doing anything
-strange, and that it will have created a local `.git` directory setup for
-your new project. You will now have a `.git` directory, and you can
-inspect that with `ls`. For your new empty project, it should show you
-three entries, among other things:
-
- - a symlink called `HEAD`, pointing to `refs/heads/master` (if your
- platform does not have native symlinks, it is a file containing the
- line "ref: refs/heads/master")
-+
-Don't worry about the fact that the file that the `HEAD` link points to
-doesn't even exist yet -- you haven't created the commit that will
-start your `HEAD` development branch yet.
-
- - a subdirectory called `objects`, which will contain all the
- objects of your project. You should never have any real reason to
- look at the objects directly, but you might want to know that these
- objects are what contains all the real 'data' in your repository.
-
- - a subdirectory called `refs`, which contains references to objects.
-
-In particular, the `refs` subdirectory will contain two other
-subdirectories, named `heads` and `tags` respectively. They do
-exactly what their names imply: they contain references to any number
-of different 'heads' of development (aka 'branches'), and to any
-'tags' that you have created to name specific versions in your
-repository.
-
-One note: the special `master` head is the default branch, which is
-why the `.git/HEAD` file was created as a symlink to it even if it
-doesn't yet exist. Basically, the `HEAD` link is supposed to always
-point to the branch you are working on right now, and you always
-start out expecting to work on the `master` branch.
-
-However, this is only a convention, and you can name your branches
-anything you want, and don't have to ever even 'have' a `master`
-branch. A number of the git tools will assume that `.git/HEAD` is
-valid, though.
-
-[NOTE]
-An 'object' is identified by its 160-bit SHA1 hash, aka 'object name',
-and a reference to an object is always the 40-byte hex
-representation of that SHA1 name. The files in the `refs`
-subdirectory are expected to contain these hex references
-(usually with a final `\'\n\'` at the end), and you should thus
-expect to see a number of 41-byte files containing these
-references in these `refs` subdirectories when you actually start
-populating your tree.
-
-[NOTE]
-An advanced user may want to take a look at the
-link:repository-layout.html[repository layout] document
-after finishing this tutorial.
-
-You have now created your first git repository. Of course, since it's
-empty, that's not very useful, so let's start populating it with data.
-
-
-Populating a git repository
----------------------------
-
-We'll keep this simple and stupid, so we'll start off with populating a
-few trivial files just to get a feel for it.
+------------------------------------------------
-Start off with just creating any random files that you want to maintain
-in your git repository. We'll start off with a few bad examples, just to
-get a feel for how this works:
+You've now initialized the working directory--you may notice a new
+directory created, named ".git". Tell git that you want it to track
+every file under the current directory with
------------------------------------------------
-$ echo "Hello World" >hello
-$ echo "Silly example" >example
+$ git add .
------------------------------------------------
-you have now created two files in your working tree (aka 'working directory'), but to
-actually check in your hard work, you will have to go through two steps:
-
- - fill in the 'index' file (aka 'cache') with the information about your
- working tree state.
+Finally,
- - commit that index file as an object.
+------------------------------------------------
+$ git commit -a
+------------------------------------------------
-The first step is trivial: when you want to tell git about any changes
-to your working tree, you use the `git-update-index` program. That
-program normally just takes a list of filenames you want to update, but
-to avoid trivial mistakes, it refuses to add new entries to the index
-(or remove existing ones) unless you explicitly tell it that you're
-adding a new entry with the `\--add` flag (or removing an entry with the
-`\--remove`) flag.
+will prompt you for a commit message, then record the current state
+of all the files to the repository.
-So to populate the index with the two files you just created, you can do
+Try modifying some files, then run
------------------------------------------------
-$ git-update-index --add hello example
+$ git diff
------------------------------------------------
-and you have now told git to track those two files.
-
-In fact, as you did that, if you now look into your object directory,
-you'll notice that git will have added two new objects to the object
-database. If you did exactly the steps above, you should now be able to do
+to review your changes. When you're done,
+------------------------------------------------
+$ git commit -a
+------------------------------------------------
-----------------
-$ ls .git/objects/??/*
-----------------
+will again prompt your for a message describing the change, and then
+record the new versions of the modified files.
-and see two files:
+A note on commit messages: Though not required, it's a good idea to
+begin the commit message with a single short (less than 50 character)
+line summarizing the change, followed by a blank line and then a more
+thorough description. Tools that turn commits into email, for
+example, use the first line on the Subject line and the rest of the
+commit in the body.
-----------------
-.git/objects/55/7db03de997c86a4a028e1ebd3a1ceb225be238
-.git/objects/f2/4c74a2e500f5ee1332c86b94199f52b1d1d962
-----------------
+To add a new file, first create the file, then
-which correspond with the objects with names of 557db... and f24c7..
-respectively.
+------------------------------------------------
+$ git add path/to/new/file
+------------------------------------------------
-If you want to, you can use `git-cat-file` to look at those objects, but
-you'll have to use the object name, not the filename of the object:
+then commit as usual. No special command is required when removing a
+file; just remove it, then commit.
-----------------
-$ git-cat-file -t 557db03de997c86a4a028e1ebd3a1ceb225be238
-----------------
+At any point you can view the history of your changes using
-where the `-t` tells `git-cat-file` to tell you what the "type" of the
-object is. git will tell you that you have a "blob" object (ie just a
-regular file), and you can see the contents with
+------------------------------------------------
+$ git whatchanged
+------------------------------------------------
-----------------
-$ git-cat-file "blob" 557db03
-----------------
+If you also want to see complete diffs at each step, use
-which will print out "Hello World". The object 557db03 is nothing
-more than the contents of your file `hello`.
+------------------------------------------------
+$ git whatchanged -p
+------------------------------------------------
-[NOTE]
-Don't confuse that object with the file `hello` itself. The
-object is literally just those specific *contents* of the file, and
-however much you later change the contents in file `hello`, the object
-we just looked at will never change. Objects are immutable.
+Managing branches
+-----------------
-[NOTE]
-The second example demonstrates that you can
-abbreviate the object name to only the first several
-hexadecimal digits in most places.
+A single git repository can maintain multiple branches of
+development. To create a new branch named "experimental", use
-Anyway, as we mentioned previously, you normally never actually take a
-look at the objects themselves, and typing long 40-character hex
-names is not something you'd normally want to do. The above digression
-was just to show that `git-update-index` did something magical, and
-actually saved away the contents of your files into the git object
-database.
+------------------------------------------------
+$ git branch experimental
+------------------------------------------------
-Updating the index did something else too: it created a `.git/index`
-file. This is the index that describes your current working tree, and
-something you should be very aware of. Again, you normally never worry
-about the index file itself, but you should be aware of the fact that
-you have not actually really "checked in" your files into git so far,
-you've only *told* git about them.
+If you now run
-However, since git knows about them, you can now start using some of the
-most basic git commands to manipulate the files or look at their status.
+------------------------------------------------
+$ git branch
+------------------------------------------------
-In particular, let's not even check in the two files into git yet, we'll
-start off by adding another line to `hello` first:
+you'll get a list of all existing branches:
------------------------------------------------
-$ echo "It's a new day for git" >>hello
+ experimental
+* master
------------------------------------------------
-and you can now, since you told git about the previous state of `hello`, ask
-git what has changed in the tree compared to your old index, using the
-`git-diff-files` command:
+The "experimental" branch is the one you just created, and the
+"master" branch is a default branch that was created for you
+automatically. The asterisk marks the branch you are currently on;
+type
-------------
-$ git-diff-files
-------------
+------------------------------------------------
+$ git checkout experimental
+------------------------------------------------
-Oops. That wasn't very readable. It just spit out its own internal
-version of a `diff`, but that internal version really just tells you
-that it has noticed that "hello" has been modified, and that the old object
-contents it had have been replaced with something else.
+to switch to the experimental branch. Now edit a file, commit the
+change, and switch back to the master branch:
-To make it readable, we can tell git-diff-files to output the
-differences as a patch, using the `-p` flag:
+------------------------------------------------
+(edit file)
+$ git commit -a
+$ git checkout master
+------------------------------------------------
-------------
-$ git-diff-files -p
-diff --git a/hello b/hello
-index 557db03..263414f 100644
---- a/hello
-+++ b/hello
-@@ -1 +1,2 @@
- Hello World
-+It's a new day for git
-----
+Check that the change you made is no longer visible, since it was
+made on the experimental branch and you're back on the master branch.
-i.e. the diff of the change we caused by adding another line to `hello`.
+You can make a different change on the master branch:
-In other words, `git-diff-files` always shows us the difference between
-what is recorded in the index, and what is currently in the working
-tree. That's very useful.
+------------------------------------------------
+(edit file)
+$ git commit -a
+------------------------------------------------
-A common shorthand for `git-diff-files -p` is to just write `git
-diff`, which will do the same thing.
+at this point the two branches have diverged, with different changes
+made in each. To merge the changes made in the two branches, run
-------------
-$ git diff
-diff --git a/hello b/hello
-index 557db03..263414f 100644
---- a/hello
-+++ b/hello
-@@ -1 +1,2 @@
- Hello World
-+It's a new day for git
-------------
-
-
-Committing git state
---------------------
-
-Now, we want to go to the next stage in git, which is to take the files
-that git knows about in the index, and commit them as a real tree. We do
-that in two phases: creating a 'tree' object, and committing that 'tree'
-object as a 'commit' object together with an explanation of what the
-tree was all about, along with information of how we came to that state.
-
-Creating a tree object is trivial, and is done with `git-write-tree`.
-There are no options or other input: git-write-tree will take the
-current index state, and write an object that describes that whole
-index. In other words, we're now tying together all the different
-filenames with their contents (and their permissions), and we're
-creating the equivalent of a git "directory" object:
+------------------------------------------------
+$ git pull . experimental
+------------------------------------------------
+
+If the changes don't conflict, you're done. If there are conflicts,
+markers will be left in the problematic files showing the conflict;
------------------------------------------------
-$ git-write-tree
+$ git diff
------------------------------------------------
-and this will just output the name of the resulting tree, in this case
-(if you have done exactly as I've described) it should be
-
-----------------
-8988da15d077d4829fc51d8544c097def6644dbb
-----------------
-
-which is another incomprehensible object name. Again, if you want to,
-you can use `git-cat-file -t 8988d\...` to see that this time the object
-is not a "blob" object, but a "tree" object (you can also use
-`git-cat-file` to actually output the raw object contents, but you'll see
-mainly a binary mess, so that's less interesting).
-
-However -- normally you'd never use `git-write-tree` on its own, because
-normally you always commit a tree into a commit object using the
-`git-commit-tree` command. In fact, it's easier to not actually use
-`git-write-tree` on its own at all, but to just pass its result in as an
-argument to `git-commit-tree`.
-
-`git-commit-tree` normally takes several arguments -- it wants to know
-what the 'parent' of a commit was, but since this is the first commit
-ever in this new repository, and it has no parents, we only need to pass in
-the object name of the tree. However, `git-commit-tree`
-also wants to get a commit message
-on its standard input, and it will write out the resulting object name for the
-commit to its standard output.
-
-And this is where we create the `.git/refs/heads/master` file
-which is pointed at by `HEAD`. This file is supposed to contain
-the reference to the top-of-tree of the master branch, and since
-that's exactly what `git-commit-tree` spits out, we can do this
-all with a sequence of simple shell commands:
+will show this. Once you've edited the files to resolve the
+conflicts,
------------------------------------------------
-$ tree=$(git-write-tree)
-$ commit=$(echo 'Initial commit' | git-commit-tree $tree)
-$ git-update-ref HEAD $commit
+$ git commit -a
------------------------------------------------
-which will say:
-
-----------------
-Committing initial tree 8988da15d077d4829fc51d8544c097def6644dbb
-----------------
-
-just to warn you about the fact that it created a totally new commit
-that is not related to anything else. Normally you do this only *once*
-for a project ever, and all later commits will be parented on top of an
-earlier commit, and you'll never see this "Committing initial tree"
-message ever again.
-
-Again, normally you'd never actually do this by hand. There is a
-helpful script called `git commit` that will do all of this for you. So
-you could have just written `git commit`
-instead, and it would have done the above magic scripting for you.
-
-
-Making a change
----------------
-
-Remember how we did the `git-update-index` on file `hello` and then we
-changed `hello` afterward, and could compare the new state of `hello` with the
-state we saved in the index file?
-
-Further, remember how I said that `git-write-tree` writes the contents
-of the *index* file to the tree, and thus what we just committed was in
-fact the *original* contents of the file `hello`, not the new ones. We did
-that on purpose, to show the difference between the index state, and the
-state in the working tree, and how they don't have to match, even
-when we commit things.
-
-As before, if we do `git-diff-files -p` in our git-tutorial project,
-we'll still see the same difference we saw last time: the index file
-hasn't changed by the act of committing anything. However, now that we
-have committed something, we can also learn to use a new command:
-`git-diff-index`.
-
-Unlike `git-diff-files`, which showed the difference between the index
-file and the working tree, `git-diff-index` shows the differences
-between a committed *tree* and either the index file or the working
-tree. In other words, `git-diff-index` wants a tree to be diffed
-against, and before we did the commit, we couldn't do that, because we
-didn't have anything to diff against.
-
-But now we can do
-
-----------------
-$ git-diff-index -p HEAD
-----------------
-
-(where `-p` has the same meaning as it did in `git-diff-files`), and it
-will show us the same difference, but for a totally different reason.
-Now we're comparing the working tree not against the index file,
-but against the tree we just wrote. It just so happens that those two
-are obviously the same, so we get the same result.
-
-Again, because this is a common operation, you can also just shorthand
-it with
-
-----------------
-$ git diff HEAD
-----------------
-
-which ends up doing the above for you.
-
-In other words, `git-diff-index` normally compares a tree against the
-working tree, but when given the `\--cached` flag, it is told to
-instead compare against just the index cache contents, and ignore the
-current working tree state entirely. Since we just wrote the index
-file to HEAD, doing `git-diff-index \--cached -p HEAD` should thus return
-an empty set of differences, and that's exactly what it does.
-
-[NOTE]
-================
-`git-diff-index` really always uses the index for its
-comparisons, and saying that it compares a tree against the working
-tree is thus not strictly accurate. In particular, the list of
-files to compare (the "meta-data") *always* comes from the index file,
-regardless of whether the `\--cached` flag is used or not. The `\--cached`
-flag really only determines whether the file *contents* to be compared
-come from the working tree or not.
-
-This is not hard to understand, as soon as you realize that git simply
-never knows (or cares) about files that it is not told about
-explicitly. git will never go *looking* for files to compare, it
-expects you to tell it what the files are, and that's what the index
-is there for.
-================
-
-However, our next step is to commit the *change* we did, and again, to
-understand what's going on, keep in mind the difference between "working
-tree contents", "index file" and "committed tree". We have changes
-in the working tree that we want to commit, and we always have to
-work through the index file, so the first thing we need to do is to
-update the index cache:
+will commit the result of the merge. Finally,
------------------------------------------------
-$ git-update-index hello
+$ gitk
------------------------------------------------
-(note how we didn't need the `\--add` flag this time, since git knew
-about the file already).
+will show a nice graphical representation of the resulting history.
-Note what happens to the different `git-diff-\*` versions here. After
-we've updated `hello` in the index, `git-diff-files -p` now shows no
-differences, but `git-diff-index -p HEAD` still *does* show that the
-current state is different from the state we committed. In fact, now
-`git-diff-index` shows the same difference whether we use the `--cached`
-flag or not, since now the index is coherent with the working tree.
+If you develop on a branch crazy-idea, then regret it, you can always
+delete the branch with
-Now, since we've updated `hello` in the index, we can commit the new
-version. We could do it by writing the tree by hand again, and
-committing the tree (this time we'd have to use the `-p HEAD` flag to
-tell commit that the HEAD was the *parent* of the new commit, and that
-this wasn't an initial commit any more), but you've done that once
-already, so let's just use the helpful script this time:
+-------------------------------------
+$ git branch -D crazy-idea
+-------------------------------------
-------------------------------------------------
-$ git commit
-------------------------------------------------
+Branches are cheap and easy, so this is a good way to try something
+out.
-which starts an editor for you to write the commit message and tells you
-a bit about what you have done.
-
-Write whatever message you want, and all the lines that start with '#'
-will be pruned out, and the rest will be used as the commit message for
-the change. If you decide you don't want to commit anything after all at
-this point (you can continue to edit things and update the index), you
-can just leave an empty message. Otherwise `git commit` will commit
-the change for you.
-
-You've now made your first real git commit. And if you're interested in
-looking at what `git commit` really does, feel free to investigate:
-it's a few very simple shell scripts to generate the helpful (?) commit
-message headers, and a few one-liners that actually do the
-commit itself (`git-commit`).
-
-
-Inspecting Changes
-------------------
-
-While creating changes is useful, it's even more useful if you can tell
-later what changed. The most useful command for this is another of the
-`diff` family, namely `git-diff-tree`.
-
-`git-diff-tree` can be given two arbitrary trees, and it will tell you the
-differences between them. Perhaps even more commonly, though, you can
-give it just a single commit object, and it will figure out the parent
-of that commit itself, and show the difference directly. Thus, to get
-the same diff that we've already seen several times, we can now do
-
-----------------
-$ git-diff-tree -p HEAD
-----------------
-
-(again, `-p` means to show the difference as a human-readable patch),
-and it will show what the last commit (in `HEAD`) actually changed.
-
-[NOTE]
-============
-Here is an ASCII art by Jon Loeliger that illustrates how
-various diff-\* commands compare things.
-
- diff-tree
- +----+
- | |
- | |
- V V
- +-----------+
- | Object DB |
- | Backing |
- | Store |
- +-----------+
- ^ ^
- | |
- | | diff-index --cached
- | |
- diff-index | V
- | +-----------+
- | | Index |
- | | "cache" |
- | +-----------+
- | ^
- | |
- | | diff-files
- | |
- V V
- +-----------+
- | Working |
- | Directory |
- +-----------+
-============
-
-More interestingly, you can also give `git-diff-tree` the `-v` flag, which
-tells it to also show the commit message and author and date of the
-commit, and you can tell it to show a whole series of diffs.
-Alternatively, you can tell it to be "silent", and not show the diffs at
-all, but just show the actual commit message.
-
-In fact, together with the `git-rev-list` program (which generates a
-list of revisions), `git-diff-tree` ends up being a veritable fount of
-changes. A trivial (but very useful) script called `git-whatchanged` is
-included with git which does exactly this, and shows a log of recent
-activities.
-
-To see the whole history of our pitiful little git-tutorial project, you
-can do
-
-----------------
-$ git log
-----------------
-
-which shows just the log messages, or if we want to see the log together
-with the associated patches use the more complex (and much more
-powerful)
-
-----------------
-$ git-whatchanged -p --root
-----------------
-
-and you will see exactly what has changed in the repository over its
-short history.
-
-[NOTE]
-The `\--root` flag is a flag to `git-diff-tree` to tell it to
-show the initial aka 'root' commit too. Normally you'd probably not
-want to see the initial import diff, but since the tutorial project
-was started from scratch and is so small, we use it to make the result
-a bit more interesting.
-
-With that, you should now be having some inkling of what git does, and
-can explore on your own.
-
-[NOTE]
-Most likely, you are not directly using the core
-git Plumbing commands, but using Porcelain like Cogito on top
-of it. Cogito works a bit differently and you usually do not
-have to run `git-update-index` yourself for changed files (you
-do tell underlying git about additions and removals via
-`cg-add` and `cg-rm` commands). Just before you make a commit
-with `cg-commit`, Cogito figures out which files you modified,
-and runs `git-update-index` on them for you.
-
-
-Tagging a version
------------------
+Using git for collaboration
+---------------------------
-In git, there are two kinds of tags, a "light" one, and an "annotated tag".
+Suppose that Alice has started a new project with a git repository in
+/home/alice/project, and that Bob, who has a home directory on the
+same machine, wants to contribute.
-A "light" tag is technically nothing more than a branch, except we put
-it in the `.git/refs/tags/` subdirectory instead of calling it a `head`.
-So the simplest form of tag involves nothing more than
+Bob begins with:
------------------------------------------------
-$ git tag my-first-tag
+$ git clone /home/alice/project myrepo
------------------------------------------------
-which just writes the current `HEAD` into the `.git/refs/tags/my-first-tag`
-file, after which point you can then use this symbolic name for that
-particular state. You can, for example, do
-
-----------------
-$ git diff my-first-tag
-----------------
-
-to diff your current state against that tag (which at this point will
-obviously be an empty diff, but if you continue to develop and commit
-stuff, you can use your tag as an "anchor-point" to see what has changed
-since you tagged it.
-
-An "annotated tag" is actually a real git object, and contains not only a
-pointer to the state you want to tag, but also a small tag name and
-message, along with optionally a PGP signature that says that yes,
-you really did
-that tag. You create these annotated tags with either the `-a` or
-`-s` flag to `git tag`:
-
-----------------
-$ git tag -s <tagname>
-----------------
-
-which will sign the current `HEAD` (but you can also give it another
-argument that specifies the thing to tag, ie you could have tagged the
-current `mybranch` point by using `git tag <tagname> mybranch`).
-
-You normally only do signed tags for major releases or things
-like that, while the light-weight tags are useful for any marking you
-want to do -- any time you decide that you want to remember a certain
-point, just create a private tag for it, and you have a nice symbolic
-name for the state at that point.
-
-
-Copying repositories
---------------------
-
-git repositories are normally totally self-sufficient and relocatable
-Unlike CVS, for example, there is no separate notion of
-"repository" and "working tree". A git repository normally *is* the
-working tree, with the local git information hidden in the `.git`
-subdirectory. There is nothing else. What you see is what you got.
-
-[NOTE]
-You can tell git to split the git internal information from
-the directory that it tracks, but we'll ignore that for now: it's not
-how normal projects work, and it's really only meant for special uses.
-So the mental model of "the git information is always tied directly to
-the working tree that it describes" may not be technically 100%
-accurate, but it's a good model for all normal use.
-
-This has two implications:
-
- - if you grow bored with the tutorial repository you created (or you've
- made a mistake and want to start all over), you can just do simple
-+
-----------------
-$ rm -rf git-tutorial
-----------------
-+
-and it will be gone. There's no external repository, and there's no
-history outside the project you created.
-
- - if you want to move or duplicate a git repository, you can do so. There
- is `git clone` command, but if all you want to do is just to
- create a copy of your repository (with all the full history that
- went along with it), you can do so with a regular
- `cp -a git-tutorial new-git-tutorial`.
-+
-Note that when you've moved or copied a git repository, your git index
-file (which caches various information, notably some of the "stat"
-information for the files involved) will likely need to be refreshed.
-So after you do a `cp -a` to create a new copy, you'll want to do
-+
-----------------
-$ git-update-index --refresh
-----------------
-+
-in the new repository to make sure that the index file is up-to-date.
-
-Note that the second point is true even across machines. You can
-duplicate a remote git repository with *any* regular copy mechanism, be it
-`scp`, `rsync` or `wget`.
-
-When copying a remote repository, you'll want to at a minimum update the
-index cache when you do this, and especially with other peoples'
-repositories you often want to make sure that the index cache is in some
-known state (you don't know *what* they've done and not yet checked in),
-so usually you'll precede the `git-update-index` with a
-
-----------------
-$ git-read-tree --reset HEAD
-$ git-update-index --refresh
-----------------
-
-which will force a total index re-build from the tree pointed to by `HEAD`.
-It resets the index contents to `HEAD`, and then the `git-update-index`
-makes sure to match up all index entries with the checked-out files.
-If the original repository had uncommitted changes in its
-working tree, `git-update-index --refresh` notices them and
-tells you they need to be updated.
-
-The above can also be written as simply
-
-----------------
-$ git reset
-----------------
-
-and in fact a lot of the common git command combinations can be scripted
-with the `git xyz` interfaces. You can learn things by just looking
-at what the various git scripts do. For example, `git reset` is the
-above two lines implemented in `git-reset`, but some things like
-`git status` and `git commit` are slightly more complex scripts around
-the basic git commands.
-
-Many (most?) public remote repositories will not contain any of
-the checked out files or even an index file, and will *only* contain the
-actual core git files. Such a repository usually doesn't even have the
-`.git` subdirectory, but has all the git files directly in the
-repository.
-
-To create your own local live copy of such a "raw" git repository, you'd
-first create your own subdirectory for the project, and then copy the
-raw repository contents into the `.git` directory. For example, to
-create your own copy of the git repository, you'd do the following
-
-----------------
-$ mkdir my-git
-$ cd my-git
-$ rsync -rL rsync://rsync.kernel.org/pub/scm/git/git.git/ .git
-----------------
-
-followed by
-
-----------------
-$ git-read-tree HEAD
-----------------
-
-to populate the index. However, now you have populated the index, and
-you have all the git internal files, but you will notice that you don't
-actually have any of the working tree files to work on. To get
-those, you'd check them out with
-
-----------------
-$ git-checkout-index -u -a
-----------------
-
-where the `-u` flag means that you want the checkout to keep the index
-up-to-date (so that you don't have to refresh it afterward), and the
-`-a` flag means "check out all files" (if you have a stale copy or an
-older version of a checked out tree you may also need to add the `-f`
-flag first, to tell git-checkout-index to *force* overwriting of any old
-files).
-
-Again, this can all be simplified with
-
-----------------
-$ git clone rsync://rsync.kernel.org/pub/scm/git/git.git/ my-git
-$ cd my-git
-$ git checkout
-----------------
-
-which will end up doing all of the above for you.
-
-You have now successfully copied somebody else's (mine) remote
-repository, and checked it out.
-
-
-Creating a new branch
----------------------
-
-Branches in git are really nothing more than pointers into the git
-object database from within the `.git/refs/` subdirectory, and as we
-already discussed, the `HEAD` branch is nothing but a symlink to one of
-these object pointers.
-
-You can at any time create a new branch by just picking an arbitrary
-point in the project history, and just writing the SHA1 name of that
-object into a file under `.git/refs/heads/`. You can use any filename you
-want (and indeed, subdirectories), but the convention is that the
-"normal" branch is called `master`. That's just a convention, though,
-and nothing enforces it.
-
-To show that as an example, let's go back to the git-tutorial repository we
-used earlier, and create a branch in it. You do that by simply just
-saying that you want to check out a new branch:
-
-------------
-$ git checkout -b mybranch
-------------
-
-will create a new branch based at the current `HEAD` position, and switch
-to it.
-
-[NOTE]
-================================================
-If you make the decision to start your new branch at some
-other point in the history than the current `HEAD`, you can do so by
-just telling `git checkout` what the base of the checkout would be.
-In other words, if you have an earlier tag or branch, you'd just do
-
-------------
-$ git checkout -b mybranch earlier-commit
-------------
-
-and it would create the new branch `mybranch` at the earlier commit,
-and check out the state at that time.
-================================================
-
-You can always just jump back to your original `master` branch by doing
-
-------------
-$ git checkout master
-------------
+This creates a new directory "myrepo" containing a clone of Alice's
+repository. The clone is on an equal footing with the original
+project, posessing its own copy of the original project's history.
+
+Bob then makes some changes and commits them:
-(or any other branch-name, for that matter) and if you forget which
-branch you happen to be on, a simple
+------------------------------------------------
+(edit files)
+$ git commit -a
+(repeat as necessary)
+------------------------------------------------
-------------
-$ ls -l .git/HEAD
-------------
+When he's ready, he tells Alice to pull changes from the repository
+at /home/bob/myrepo. She does this with:
-will tell you where it's pointing (Note that on platforms with bad or no
-symlink support, you have to execute
+------------------------------------------------
+$ cd /home/alice/project
+$ git pull /home/bob/myrepo
+------------------------------------------------
-------------
-$ cat .git/HEAD
-------------
+This actually pulls changes from the branch in Bob's repository named
+"master". Alice could request a different branch by adding the name
+of the branch to the end of the git pull command line.
-instead). To get the list of branches you have, you can say
+This merges Bob's changes into her repository; "git whatchanged" 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.
-------------
-$ git branch
-------------
+A more cautious Alice might wish to examine Bob's changes before
+pulling them. She can do this by creating a temporary branch just
+for the purpose of studying Bob's changes:
-which is nothing more than a simple script around `ls .git/refs/heads`.
-There will be asterisk in front of the branch you are currently on.
+-------------------------------------
+$ git fetch /home/bob/myrepo master:bob-incoming
+-------------------------------------
-Sometimes you may wish to create a new branch _without_ actually
-checking it out and switching to it. If so, just use the command
+which fetches the changes from Bob's master branch into a new branch
+named bob-incoming. (Unlike git pull, git fetch just fetches a copy
+of Bob's line of development without doing any merging). Then
-------------
-$ git branch <branchname> [startingpoint]
-------------
+-------------------------------------
+$ git whatchanged -p master..bob-incoming
+-------------------------------------
-which will simply _create_ the branch, but will not do anything further.
-You can then later -- once you decide that you want to actually develop
-on that branch -- switch to that branch with a regular `git checkout`
-with the branchname as the argument.
+shows a list of all the changes that Bob made since he branched from
+Alice's master branch.
+After examing those changes, and possibly fixing things, Alice can
+pull the changes into her master branch:
-Merging two branches
---------------------
+-------------------------------------
+$ git checkout master
+$ git pull . bob-incoming
+-------------------------------------
-One of the ideas of having a branch is that you do some (possibly
-experimental) work in it, and eventually merge it back to the main
-branch. So assuming you created the above `mybranch` that started out
-being the same as the original `master` branch, let's make sure we're in
-that branch, and do some work there.
+The last command is a pull from the "bob-incoming" branch in Alice's
+own repository.
-------------------------------------------------
-$ git checkout mybranch
-$ echo "Work, work, work" >>hello
-$ git commit -m 'Some work.' hello
-------------------------------------------------
+Later, Bob can update his repo with Alice's latest changes using
-Here, we just added another line to `hello`, and we used a shorthand for
-doing both `git-update-index hello` and `git commit` by just giving the
-filename directly to `git commit`. The `-m` flag is to give the
-commit log message from the command line.
+-------------------------------------
+$ git pull
+-------------------------------------
-Now, to make it a bit more interesting, let's assume that somebody else
-does some work in the original branch, and simulate that by going back
-to the master branch, and editing the same file differently there:
+Note that he doesn't need to give the path to Alice's repository;
+when Bob cloned Alice's repository, git stored the location of her
+repository in the file .git/remotes/origin, and that location is used
+as the default for pulls.
-------------
-$ git checkout master
-------------
-
-Here, take a moment to look at the contents of `hello`, and notice how they
-don't contain the work we just did in `mybranch` -- because that work
-hasn't happened in the `master` branch at all. Then do
-
-------------
-$ echo "Play, play, play" >>hello
-$ echo "Lots of fun" >>example
-$ git commit -m 'Some fun.' hello example
-------------
-
-since the master branch is obviously in a much better mood.
-
-Now, you've got two branches, and you decide that you want to merge the
-work done. Before we do that, let's introduce a cool graphical tool that
-helps you view what's going on:
-
-----------------
-$ gitk --all
-----------------
-
-will show you graphically both of your branches (that's what the `\--all`
-means: normally it will just show you your current `HEAD`) and their
-histories. You can also see exactly how they came to be from a common
-source.
-
-Anyway, let's exit `gitk` (`^Q` or the File menu), and decide that we want
-to merge the work we did on the `mybranch` branch into the `master`
-branch (which is currently our `HEAD` too). To do that, there's a nice
-script called `git merge`, which wants to know which branches you want
-to resolve and what the merge is all about:
-
-------------
-$ git merge "Merge work in mybranch" HEAD mybranch
-------------
-
-where the first argument is going to be used as the commit message if
-the merge can be resolved automatically.
-
-Now, in this case we've intentionally created a situation where the
-merge will need to be fixed up by hand, though, so git will do as much
-of it as it can automatically (which in this case is just merge the `example`
-file, which had no differences in the `mybranch` branch), and say:
-
-----------------
- Trying really trivial in-index merge...
- fatal: Merge requires file-level merging
- Nope.
- ...
- Auto-merging hello
- CONFLICT (content): Merge conflict in hello
- Automatic merge failed/prevented; fix up by hand
-----------------
-
-which is way too verbose, but it basically tells you that it failed the
-really trivial merge ("Simple merge") and did an "Automatic merge"
-instead, but that too failed due to conflicts in `hello`.
-
-Not to worry. It left the (trivial) conflict in `hello` in the same form you
-should already be well used to if you've ever used CVS, so let's just
-open `hello` in our editor (whatever that may be), and fix it up somehow.
-I'd suggest just making it so that `hello` contains all four lines:
-
-------------
-Hello World
-It's a new day for git
-Play, play, play
-Work, work, work
-------------
-
-and once you're happy with your manual merge, just do a
-
-------------
-$ git commit hello
-------------
-
-which will very loudly warn you that you're now committing a merge
-(which is correct, so never mind), and you can write a small merge
-message about your adventures in git-merge-land.
-
-After you're done, start up `gitk \--all` to see graphically what the
-history looks like. Notice that `mybranch` still exists, and you can
-switch to it, and continue to work with it if you want to. The
-`mybranch` branch will not contain the merge, but next time you merge it
-from the `master` branch, git will know how you merged it, so you'll not
-have to do _that_ merge again.
-
-Another useful tool, especially if you do not always work in X-Window
-environment, is `git show-branch`.
+Bob may also notice a branch in his repository that he didn't create:
-------------------------------------------------
-$ git show-branch master mybranch
-* [master] Merge work in mybranch
- ! [mybranch] Some work.
---
-- [master] Merge work in mybranch
-*+ [mybranch] Some work.
-------------------------------------------------
+-------------------------------------
+$ git branch
+* master
+ origin
+-------------------------------------
-The first two lines indicate that it is showing the two branches
-and the first line of the commit log message from their
-top-of-the-tree commits, you are currently on `master` branch
-(notice the asterisk `*` character), and the first column for
-the later output lines is used to show commits contained in the
-`master` branch, and the second column for the `mybranch`
-branch. Three commits are shown along with their log messages.
-All of them have non blank characters in the first column (`*`
-shows an ordinary commit on the current branch, `.` is a merge commit), which
-means they are now part of the `master` branch. Only the "Some
-work" commit has the plus `+` character in the second column,
-because `mybranch` has not been merged to incorporate these
-commits from the master branch. The string inside brackets
-before the commit log message is a short name you can use to
-name the commit. In the above example, 'master' and 'mybranch'
-are branch heads. 'master~1' is the first parent of 'master'
-branch head. Please see 'git-rev-parse' documentation if you
-see more complex cases.
-
-Now, let's pretend you are the one who did all the work in
-`mybranch`, and the fruit of your hard work has finally been merged
-to the `master` branch. Let's go back to `mybranch`, and run
-resolve to get the "upstream changes" back to your branch.
-
-------------
-$ git checkout mybranch
-$ git merge "Merge upstream changes." HEAD master
-------------
-
-This outputs something like this (the actual commit object names
-would be different)
-
-----------------
-Updating from ae3a2da... to a80b4aa....
- example | 1 +
- hello | 1 +
- 2 files changed, 2 insertions(+), 0 deletions(-)
-----------------
-
-Because your branch did not contain anything more than what are
-already merged into the `master` branch, the resolve operation did
-not actually do a merge. Instead, it just updated the top of
-the tree of your branch to that of the `master` branch. This is
-often called 'fast forward' merge.
-
-You can run `gitk \--all` again to see how the commit ancestry
-looks like, or run `show-branch`, which tells you this.
+The "origin" branch, which was created automatically by "git clone",
+is a pristine copy of Alice's master branch; Bob should never commit
+to it.
-------------------------------------------------
-$ git show-branch master mybranch
-! [master] Merge work in mybranch
- * [mybranch] Merge work in mybranch
---
--- [master] Merge work in mybranch
-------------------------------------------------
+If Bob later decides to work from a different host, he can still
+perform clones and pulls using the ssh protocol:
+-------------------------------------
+$ git clone alice.org:/home/alice/project myrepo
+-------------------------------------
-Merging external work
----------------------
-
-It's usually much more common that you merge with somebody else than
-merging with your own branches, so it's worth pointing out that git
-makes that very easy too, and in fact, it's not that different from
-doing a `git merge`. In fact, a remote merge ends up being nothing
-more than "fetch the work from a remote repository into a temporary tag"
-followed by a `git merge`.
-
-Fetching from a remote repository is done by, unsurprisingly,
-`git fetch`:
-
-----------------
-$ git fetch <remote-repository>
-----------------
-
-One of the following transports can be used to name the
-repository to download from:
-
-Rsync::
- `rsync://remote.machine/path/to/repo.git/`
-+
-Rsync transport is usable for both uploading and downloading,
-but is completely unaware of what git does, and can produce
-unexpected results when you download from the public repository
-while the repository owner is uploading into it via `rsync`
-transport. Most notably, it could update the files under
-`refs/` which holds the object name of the topmost commits
-before uploading the files in `objects/` -- the downloader would
-obtain head commit object name while that object itself is still
-not available in the repository. For this reason, it is
-considered deprecated.
-
-SSH::
- `remote.machine:/path/to/repo.git/` or
-+
-`ssh://remote.machine/path/to/repo.git/`
-+
-This transport can be used for both uploading and downloading,
-and requires you to have a log-in privilege over `ssh` to the
-remote machine. It finds out the set of objects the other side
-lacks by exchanging the head commits both ends have and
-transfers (close to) minimum set of objects. It is by far the
-most efficient way to exchange git objects between repositories.
-
-Local directory::
- `/path/to/repo.git/`
-+
-This transport is the same as SSH transport but uses `sh` to run
-both ends on the local machine instead of running other end on
-the remote machine via `ssh`.
-
-git Native::
- `git://remote.machine/path/to/repo.git/`
-+
-This transport was designed for anonymous downloading. Like SSH
-transport, it finds out the set of objects the downstream side
-lacks and transfers (close to) minimum set of objects.
-
-HTTP(S)::
- `http://remote.machine/path/to/repo.git/`
-+
-Downloader from http and https URL
-first obtains the topmost commit object name from the remote site
-by looking at the specified refname under `repo.git/refs/` directory,
-and then tries to obtain the
-commit object by downloading from `repo.git/objects/xx/xxx\...`
-using the object name of that commit object. Then it reads the
-commit object to find out its parent commits and the associate
-tree object; it repeats this process until it gets all the
-necessary objects. Because of this behaviour, they are
-sometimes also called 'commit walkers'.
-+
-The 'commit walkers' are sometimes also called 'dumb
-transports', because they do not require any git aware smart
-server like git Native transport does. Any stock HTTP server
-that does not even support directory index would suffice. But
-you must prepare your repository with `git-update-server-info`
-to help dumb transport downloaders.
-+
-There are (confusingly enough) `git-ssh-fetch` and `git-ssh-upload`
-programs, which are 'commit walkers'; they outlived their
-usefulness when git Native and SSH transports were introduced,
-and not used by `git pull` or `git push` scripts.
-
-Once you fetch from the remote repository, you `resolve` that
-with your current branch.
-
-However -- it's such a common thing to `fetch` and then
-immediately `resolve`, that it's called `git pull`, and you can
-simply do
-
-----------------
-$ git pull <remote-repository>
-----------------
-
-and optionally give a branch-name for the remote end as a second
-argument.
-
-[NOTE]
-You could do without using any branches at all, by
-keeping as many local repositories as you would like to have
-branches, and merging between them with `git pull`, just like
-you merge between branches. The advantage of this approach is
-that it lets you keep set of files for each `branch` checked
-out and you may find it easier to switch back and forth if you
-juggle multiple lines of development simultaneously. Of
-course, you will pay the price of more disk usage to hold
-multiple working trees, but disk space is cheap these days.
-
-[NOTE]
-You could even pull from your own repository by
-giving '.' as <remote-repository> parameter to `git pull`. This
-is useful when you want to merge a local branch (or more, if you
-are making an Octopus) into the current branch.
-
-It is likely that you will be pulling from the same remote
-repository from time to time. As a short hand, you can store
-the remote repository URL in a file under .git/remotes/
-directory, like this:
+Alternatively, git has a native protocol, or can use rsync or http;
+see gitlink:git-pull[1] for details.
-------------------------------------------------
-$ mkdir -p .git/remotes/
-$ cat >.git/remotes/linus <<\EOF
-URL: http://www.kernel.org/pub/scm/git/git.git/
-EOF
-------------------------------------------------
+Git can also be used in a CVS-like mode, with a central repository
+that various users push changes to; see gitlink:git-push[1] and
+link:cvs-migration.html[git for CVS users].
-and use the filename to `git pull` instead of the full URL.
-The URL specified in such file can even be a prefix
-of a full URL, like this:
+Keeping track of history
+------------------------
-------------------------------------------------
-$ cat >.git/remotes/jgarzik <<\EOF
-URL: http://www.kernel.org/pub/scm/linux/git/jgarzik/
-EOF
-------------------------------------------------
+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 diff HEAD^ HEAD
+-------------------------------------
-Examples.
+shows the difference between the most-recently checked-in state of
+the tree and the previous state, and
-. `git pull linus`
-. `git pull linus tag v0.99.1`
-. `git pull jgarzik/netdev-2.6.git/ e100`
+-------------------------------------
+git diff HEAD^^ HEAD^
+-------------------------------------
-the above are equivalent to:
+shows the difference between that previous state and the state two
+commits ago. Also, HEAD~5 can be used as a shorthand for HEAD^^^^^,
+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].
-. `git pull http://www.kernel.org/pub/scm/git/git.git/ HEAD`
-. `git pull http://www.kernel.org/pub/scm/git/git.git/ tag v0.99.1`
-. `git pull http://www.kernel.org/pub/.../jgarzik/netdev-2.6.git e100`
+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
+-------------------------------------
+git diff HEAD experimental
+-------------------------------------
-How does the merge work?
-------------------------
+to see the difference between the most-recently committed tree in
+the current branch and the most-recently committed tree in the
+experimental branch.
-We said this tutorial shows what plumbing does to help you cope
-with the porcelain that isn't flushing, but we so far did not
-talk about how the merge really works. If you are following
-this tutorial the first time, I'd suggest to skip to "Publishing
-your work" section and come back here later.
-
-OK, still with me? To give us an example to look at, let's go
-back to the earlier repository with "hello" and "example" file,
-and bring ourselves back to the pre-merge state:
-
-------------
-$ git show-branch --more=3 master mybranch
-! [master] Merge work in mybranch
- * [mybranch] Merge work in mybranch
---
--- [master] Merge work in mybranch
-+* [master^2] Some work.
-+* [master^] Some fun.
-------------
-
-Remember, before running `git merge`, our `master` head was at
-"Some fun." commit, while our `mybranch` head was at "Some
-work." commit.
-
-------------
-$ git checkout mybranch
-$ git reset --hard master^2
-$ git checkout master
-$ git reset --hard master^
-------------
-
-After rewinding, the commit structure should look like this:
-
-------------
-$ git show-branch
-* [master] Some fun.
- ! [mybranch] Some work.
---
- + [mybranch] Some work.
-* [master] Some fun.
-*+ [mybranch^] New day.
-------------
-
-Now we are ready to experiment with the merge by hand.
-
-`git merge` command, when merging two branches, uses 3-way merge
-algorithm. First, it finds the common ancestor between them.
-The command it uses is `git-merge-base`:
-
-------------
-$ mb=$(git-merge-base HEAD mybranch)
-------------
-
-The command writes the commit object name of the common ancestor
-to the standard output, so we captured its output to a variable,
-because we will be using it in the next step. BTW, the common
-ancestor commit is the "New day." commit in this case. You can
-tell it by:
-
-------------
-$ git-name-rev $mb
-my-first-tag
-------------
-
-After finding out a common ancestor commit, the second step is
-this:
-
-------------
-$ git-read-tree -m -u $mb HEAD mybranch
-------------
-
-This is the same `git-read-tree` command we have already seen,
-but it takes three trees, unlike previous examples. This reads
-the contents of each tree into different 'stage' in the index
-file (the first tree goes to stage 1, the second stage 2,
-etc.). After reading three trees into three stages, the paths
-that are the same in all three stages are 'collapsed' into stage
-0. Also paths that are the same in two of three stages are
-collapsed into stage 0, taking the SHA1 from either stage 2 or
-stage 3, whichever is different from stage 1 (i.e. only one side
-changed from the common ancestor).
-
-After 'collapsing' operation, paths that are different in three
-trees are left in non-zero stages. At this point, you can
-inspect the index file with this command:
-
-------------
-$ git-ls-files --stage
-100644 7f8b141b65fdcee47321e399a2598a235a032422 0 example
-100644 263414f423d0e4d70dae8fe53fa34614ff3e2860 1 hello
-100644 06fa6a24256dc7e560efa5687fa84b51f0263c3a 2 hello
-100644 cc44c73eb783565da5831b4d820c962954019b69 3 hello
-------------
-
-In our example of only two files, we did not have unchanged
-files so only 'example' resulted in collapsing, but in real-life
-large projects, only small number of files change in one commit,
-and this 'collapsing' tends to trivially merge most of the paths
-fairly quickly, leaving only a handful the real changes in non-zero
-stages.
-
-To look at only non-zero stages, use `\--unmerged` flag:
-
-------------
-$ git-ls-files --unmerged
-100644 263414f423d0e4d70dae8fe53fa34614ff3e2860 1 hello
-100644 06fa6a24256dc7e560efa5687fa84b51f0263c3a 2 hello
-100644 cc44c73eb783565da5831b4d820c962954019b69 3 hello
-------------
-
-The next step of merging is to merge these three versions of the
-file, using 3-way merge. This is done by giving
-`git-merge-one-file` command as one of the arguments to
-`git-merge-index` command:
-
-------------
-$ git-merge-index git-merge-one-file hello
-Auto-merging hello.
-merge: warning: conflicts during merge
-ERROR: Merge conflict in hello.
-fatal: merge program failed
-------------
-
-`git-merge-one-file` script is called with parameters to
-describe those three versions, and is responsible to leave the
-merge results in the working tree.
-It is a fairly straightforward shell script, and
-eventually calls `merge` program from RCS suite to perform a
-file-level 3-way merge. In this case, `merge` detects
-conflicts, and the merge result with conflict marks is left in
-the working tree.. This can be seen if you run `ls-files
---stage` again at this point:
-
-------------
-$ git-ls-files --stage
-100644 7f8b141b65fdcee47321e399a2598a235a032422 0 example
-100644 263414f423d0e4d70dae8fe53fa34614ff3e2860 1 hello
-100644 06fa6a24256dc7e560efa5687fa84b51f0263c3a 2 hello
-100644 cc44c73eb783565da5831b4d820c962954019b69 3 hello
-------------
-
-This is the state of the index file and the working file after
-`git merge` returns control back to you, leaving the conflicting
-merge for you to resolve. Notice that the path `hello` is still
-unmerged, and what you see with `git diff` at this point is
-differences since stage 2 (i.e. your version).
-
-
-Publishing your work
---------------------
-
-So we can use somebody else's work from a remote repository; but
-how can *you* prepare a repository to let other people pull from
-it?
-
-Your do your real work in your working tree that has your
-primary repository hanging under it as its `.git` subdirectory.
-You *could* make that repository accessible remotely and ask
-people to pull from it, but in practice that is not the way
-things are usually done. A recommended way is to have a public
-repository, make it reachable by other people, and when the
-changes you made in your primary working tree are in good shape,
-update the public repository from it. This is often called
-'pushing'.
-
-[NOTE]
-This public repository could further be mirrored, and that is
-how git repositories at `kernel.org` are managed.
-
-Publishing the changes from your local (private) repository to
-your remote (public) repository requires a write privilege on
-the remote machine. You need to have an SSH account there to
-run a single command, `git-receive-pack`.
-
-First, you need to create an empty repository on the remote
-machine that will house your public repository. This empty
-repository will be populated and be kept up-to-date by pushing
-into it later. Obviously, this repository creation needs to be
-done only once.
-
-[NOTE]
-`git push` uses a pair of programs,
-`git-send-pack` on your local machine, and `git-receive-pack`
-on the remote machine. The communication between the two over
-the network internally uses an SSH connection.
-
-Your private repository's git directory is usually `.git`, but
-your public repository is often named after the project name,
-i.e. `<project>.git`. Let's create such a public repository for
-project `my-git`. After logging into the remote machine, create
-an empty directory:
-
-------------
-$ mkdir my-git.git
-------------
-
-Then, make that directory into a git repository by running
-`git init-db`, but this time, since its name is not the usual
-`.git`, we do things slightly differently:
-
-------------
-$ GIT_DIR=my-git.git git-init-db
-------------
-
-Make sure this directory is available for others you want your
-changes to be pulled by via the transport of your choice. Also
-you need to make sure that you have the `git-receive-pack`
-program on the `$PATH`.
-
-[NOTE]
-Many installations of sshd do not invoke your shell as the login
-shell when you directly run programs; what this means is that if
-your login shell is `bash`, only `.bashrc` is read and not
-`.bash_profile`. As a workaround, make sure `.bashrc` sets up
-`$PATH` so that you can run `git-receive-pack` program.
-
-[NOTE]
-If you plan to publish this repository to be accessed over http,
-you should do `chmod +x my-git.git/hooks/post-update` at this
-point. This makes sure that every time you push into this
-repository, `git-update-server-info` is run.
-
-Your "public repository" is now ready to accept your changes.
-Come back to the machine you have your private repository. From
-there, run this command:
-
-------------
-$ git push <public-host>:/path/to/my-git.git master
-------------
-
-This synchronizes your public repository to match the named
-branch head (i.e. `master` in this case) and objects reachable
-from them in your current repository.
-
-As a real example, this is how I update my public git
-repository. Kernel.org mirror network takes care of the
-propagation to other publicly visible machines:
-
-------------
-$ git push master.kernel.org:/pub/scm/git/git.git/
-------------
-
-
-Packing your repository
------------------------
+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
-Earlier, we saw that one file under `.git/objects/??/` directory
-is stored for each git object you create. This representation
-is efficient to create atomically and safely, but
-not so convenient to transport over the network. Since git objects are
-immutable once they are created, there is a way to optimize the
-storage by "packing them together". The command
-
-------------
-$ git repack
-------------
-
-will do it for you. If you followed the tutorial examples, you
-would have accumulated about 17 objects in `.git/objects/??/`
-directories by now. `git repack` tells you how many objects it
-packed, and stores the packed file in `.git/objects/pack`
-directory.
-
-[NOTE]
-You will see two files, `pack-\*.pack` and `pack-\*.idx`,
-in `.git/objects/pack` directory. They are closely related to
-each other, and if you ever copy them by hand to a different
-repository for whatever reason, you should make sure you copy
-them together. The former holds all the data from the objects
-in the pack, and the latter holds the index for random
-access.
-
-If you are paranoid, running `git-verify-pack` command would
-detect if you have a corrupt pack, but do not worry too much.
-Our programs are always perfect ;-).
-
-Once you have packed objects, you do not need to leave the
-unpacked objects that are contained in the pack file anymore.
-
-------------
-$ git prune-packed
-------------
-
-would remove them for you.
-
-You can try running `find .git/objects -type f` before and after
-you run `git prune-packed` if you are curious. Also `git
-count-objects` would tell you how many unpacked objects are in
-your repository and how much space they are consuming.
-
-[NOTE]
-`git pull` is slightly cumbersome for HTTP transport, as a
-packed repository may contain relatively few objects in a
-relatively large pack. If you expect many HTTP pulls from your
-public repository you might want to repack & prune often, or
-never.
-
-If you run `git repack` again at this point, it will say
-"Nothing to pack". Once you continue your development and
-accumulate the changes, running `git repack` again will create a
-new pack, that contains objects created since you packed your
-repository the last time. We recommend that you pack your project
-soon after the initial import (unless you are starting your
-project from scratch), and then run `git repack` every once in a
-while, depending on how active your project is.
-
-When a repository is synchronized via `git push` and `git pull`
-objects packed in the source repository are usually stored
-unpacked in the destination, unless rsync transport is used.
-While this allows you to use different packing strategies on
-both ends, it also means you may need to repack both
-repositories every once in a while.
-
-
-Working with Others
--------------------
-
-Although git is a truly distributed system, it is often
-convenient to organize your project with an informal hierarchy
-of developers. Linux kernel development is run this way. There
-is a nice illustration (page 17, "Merges to Mainline") in Randy
-Dunlap's presentation (`http://tinyurl.com/a2jdg`).
-
-It should be stressed that this hierarchy is purely *informal*.
-There is nothing fundamental in git that enforces the "chain of
-patch flow" this hierarchy implies. You do not have to pull
-from only one remote repository.
-
-A recommended workflow for a "project lead" goes like this:
-
-1. Prepare your primary repository on your local machine. Your
- work is done there.
-
-2. Prepare a public repository accessible to others.
-+
-If other people are pulling from your repository over dumb
-transport protocols (HTTP), you need to keep this repository
-'dumb transport friendly'. After `git init-db`,
-`$GIT_DIR/hooks/post-update` copied from the standard templates
-would contain a call to `git-update-server-info` but the
-`post-update` hook itself is disabled by default -- enable it
-with `chmod +x post-update`. This makes sure `git-update-server-info`
-keeps the necessary files up-to-date.
-
-3. Push into the public repository from your primary
- repository.
-
-4. `git repack` the public repository. This establishes a big
- pack that contains the initial set of objects as the
- baseline, and possibly `git prune` if the transport
- used for pulling from your repository supports packed
- repositories.
-
-5. Keep working in your primary repository. Your changes
- include modifications of your own, patches you receive via
- e-mails, and merges resulting from pulling the "public"
- repositories of your "subsystem maintainers".
-+
-You can repack this private repository whenever you feel like.
-
-6. Push your changes to the public repository, and announce it
- to the public.
-
-7. Every once in a while, "git repack" the public repository.
- Go back to step 5. and continue working.
-
-
-A recommended work cycle for a "subsystem maintainer" who works
-on that project and has an own "public repository" goes like this:
-
-1. Prepare your work repository, by `git clone` the public
- repository of the "project lead". The URL used for the
- initial cloning is stored in `.git/remotes/origin`.
-
-2. Prepare a public repository accessible to others, just like
- the "project lead" person does.
-
-3. Copy over the packed files from "project lead" public
- repository to your public repository, unless the "project
- lead" repository lives on the same machine as yours. In the
- latter case, you can use `objects/info/alternates` file to
- point at the repository you are borrowing from.
-
-4. Push into the public repository from your primary
- repository. Run `git repack`, and possibly `git prune` if the
- transport used for pulling from your repository supports
- packed repositories.
-
-5. Keep working in your primary repository. Your changes
- include modifications of your own, patches you receive via
- e-mails, and merges resulting from pulling the "public"
- repositories of your "project lead" and possibly your
- "sub-subsystem maintainers".
-+
-You can repack this private repository whenever you feel
-like.
-
-6. Push your changes to your public repository, and ask your
- "project lead" and possibly your "sub-subsystem
- maintainers" to pull from it.
-
-7. Every once in a while, `git repack` the public repository.
- Go back to step 5. and continue working.
-
-
-A recommended work cycle for an "individual developer" who does
-not have a "public" repository is somewhat different. It goes
-like this:
-
-1. Prepare your work repository, by `git clone` the public
- repository of the "project lead" (or a "subsystem
- maintainer", if you work on a subsystem). The URL used for
- the initial cloning is stored in `.git/remotes/origin`.
-
-2. Do your work in your repository on 'master' branch.
-
-3. Run `git fetch origin` from the public repository of your
- upstream every once in a while. This does only the first
- half of `git pull` but does not merge. The head of the
- public repository is stored in `.git/refs/heads/origin`.
-
-4. Use `git cherry origin` to see which ones of your patches
- were accepted, and/or use `git rebase origin` to port your
- unmerged changes forward to the updated upstream.
-
-5. Use `git format-patch origin` to prepare patches for e-mail
- submission to your upstream and send it out. Go back to
- step 2. and continue.
+-------------------------------------
+git whatchanged HEAD..experimental
+-------------------------------------
+will do that, just as
-Working with Others, Shared Repository Style
---------------------------------------------
-
-If you are coming from CVS background, the style of cooperation
-suggested in the previous section may be new to you. You do not
-have to worry. git supports "shared public repository" style of
-cooperation you are probably more familiar with as well.
+-------------------------------------
+git whatchanged experimental..HEAD
+-------------------------------------
-For this, set up a public repository on a machine that is
-reachable via SSH by people with "commit privileges". Put the
-committers in the same user group and make the repository
-writable by that group. Make sure their umasks are set up to
-allow group members to write into directories other members
-have created.
+will show the list of commits made on the HEAD but not included in
+experimental.
-You, as an individual committer, then:
+You can also give commits convenient names of your own: after running
-- First clone the shared repository to a local repository:
-------------------------------------------------
-$ git clone repo.shared.xz:/pub/scm/project.git/ my-project
-$ cd my-project
-$ hack away
-------------------------------------------------
+-------------------------------------
+$ git-tag v2.5 HEAD^^
+-------------------------------------
-- Merge the work others might have done while you were hacking
- away:
-------------------------------------------------
-$ git pull origin
-$ test the merge result
-------------------------------------------------
-[NOTE]
-================================
-The first `git clone` would have placed the following in
-`my-project/.git/remotes/origin` file, and that's why this and
-the next step work.
-------------
-URL: repo.shared.xz:/pub/scm/project.git/ my-project
-Pull: master:origin
-------------
-================================
-
-- push your work as the new head of the shared
- repository.
-------------------------------------------------
-$ git push origin master
-------------------------------------------------
-If somebody else pushed into the same shared repository while
-you were working locally, `git push` in the last step would
-complain, telling you that the remote `master` head does not
-fast forward. You need to pull and merge those other changes
-back before you push your work when it happens.
+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.
+You can revisit the old state of a tree, and make further
+modifications if you wish, using git branch: the command
-Advanced Shared Repository Management
+-------------------------------------
+$ git branch stable-release v2.5
-------------------------------------
-Being able to push into a shared repository means being able to
-write into it. If your developers are coming over the network,
-this means you, as the repository administrator, need to give
-each of them an SSH access to the shared repository machine.
-
-In some cases, though, you may not want to give a normal shell
-account to them, but want to restrict them to be able to only
-do `git push` into the repository and nothing else.
-
-You can achieve this by setting the login shell of your
-developers on the shared repository host to `git-shell` program.
-
-[NOTE]
-Most likely you would also need to list `git-shell` program in
-`/etc/shells` file.
-
-This restricts the set of commands that can be run from incoming
-SSH connection for these users to only `receive-pack` and
-`upload-pack`, so the only thing they can do are `git fetch` and
-`git push`.
-
-You still need to create UNIX user accounts for each developer,
-and put them in the same group. Make sure that the repository
-shared among these developers is writable by that group.
-
-. Initializing the shared repository with `git-init-db --shared`
-helps somewhat.
-
-. Run the following in the shared repository:
-+
-------------
-$ chgrp -R $group repo.git
-$ find repo.git -type d -print | xargs chmod ug+rwx,g+s
-$ GIT_DIR=repo.git git repo-config core.sharedrepository true
-------------
-
-The above measures make sure that directories lazily created in
-`$GIT_DIR` are writable by group members. You, as the
-repository administrator, are still responsible to make sure
-your developers belong to that shared repository group and set
-their umask to a value no stricter than 027 (i.e. at least allow
-reading and searching by group members).
-
-You can implement finer grained branch policies using update
-hooks. There is a document ("control access to branches") in
-Documentation/howto by Carl Baldwin and JC outlining how to (1)
-limit access to branch per user, (2) forbid overwriting existing
-tags.
-
-
-Bundling your work together
----------------------------
+will create a new branch named "stable-release" starting from the
+commit which you tagged with the name v2.5.
+
+You can reset the state of any branch to an earlier commit at any
+time with
+
+-------------------------------------
+$ git reset --hard v2.5
+-------------------------------------
-It is likely that you will be working on more than one thing at
-a time. It is easy to manage those more-or-less independent tasks
-using branches with git.
-
-We have already seen how branches work previously,
-with "fun and work" example using two branches. The idea is the
-same if there are more than two branches. Let's say you started
-out from "master" head, and have some new code in the "master"
-branch, and two independent fixes in the "commit-fix" and
-"diff-fix" branches:
-
-------------
-$ git show-branch
-! [commit-fix] Fix commit message normalization.
- ! [diff-fix] Fix rename detection.
- * [master] Release candidate #1
----
- + [diff-fix] Fix rename detection.
- + [diff-fix~1] Better common substring algorithm.
-+ [commit-fix] Fix commit message normalization.
- * [master] Release candidate #1
-++* [diff-fix~2] Pretty-print messages.
-------------
-
-Both fixes are tested well, and at this point, you want to merge
-in both of them. You could merge in 'diff-fix' first and then
-'commit-fix' next, like this:
-
-------------
-$ git merge 'Merge fix in diff-fix' master diff-fix
-$ git merge 'Merge fix in commit-fix' master commit-fix
-------------
-
-Which would result in:
-
-------------
-$ git show-branch
-! [commit-fix] Fix commit message normalization.
- ! [diff-fix] Fix rename detection.
- * [master] Merge fix in commit-fix
----
- - [master] Merge fix in commit-fix
-+ * [commit-fix] Fix commit message normalization.
- - [master~1] Merge fix in diff-fix
- +* [diff-fix] Fix rename detection.
- +* [diff-fix~1] Better common substring algorithm.
- * [master~2] Release candidate #1
-++* [master~3] Pretty-print messages.
-------------
-
-However, there is no particular reason to merge in one branch
-first and the other next, when what you have are a set of truly
-independent changes (if the order mattered, then they are not
-independent by definition). You could instead merge those two
-branches into the current branch at once. First let's undo what
-we just did and start over. We would want to get the master
-branch before these two merges by resetting it to 'master~2':
-
-------------
-$ git reset --hard master~2
-------------
-
-You can make sure 'git show-branch' matches the state before
-those two 'git merge' you just did. Then, instead of running
-two 'git merge' commands in a row, you would pull these two
-branch heads (this is known as 'making an Octopus'):
-
-------------
-$ git pull . commit-fix diff-fix
-$ git show-branch
-! [commit-fix] Fix commit message normalization.
- ! [diff-fix] Fix rename detection.
- * [master] Octopus merge of branches 'diff-fix' and 'commit-fix'
----
- - [master] Octopus merge of branches 'diff-fix' and 'commit-fix'
-+ * [commit-fix] Fix commit message normalization.
- +* [diff-fix] Fix rename detection.
- +* [diff-fix~1] Better common substring algorithm.
- * [master~1] Release candidate #1
-++* [master~2] Pretty-print messages.
-------------
-
-Note that you should not do Octopus because you can. An octopus
-is a valid thing to do and often makes it easier to view the
-commit history if you are pulling more than two independent
-changes at the same time. However, if you have merge conflicts
-with any of the branches you are merging in and need to hand
-resolve, that is an indication that the development happened in
-those branches were not independent after all, and you should
-merge two at a time, documenting how you resolved the conflicts,
-and the reason why you preferred changes made in one side over
-the other. Otherwise it would make the project history harder
-to follow, not easier.
-
-[ to be continued.. cvsimports ]
+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.
+
+Next Steps
+----------
+
+Some good commands to explore next:
+
+ * gitlink:git-diff[1]: This flexible command does much more than
+ we've seen in the few examples above.
+
+ * gitlink:git-format-patch[1], gitlink:git-am[1]: These convert
+ series of git commits into emailed patches, and vice versa,
+ useful for projects such as the linux kernel which rely heavily
+ on emailed patches.
+
+ * gitlink:git-bisect[1]: When there is a regression in your
+ project, one way to track down the bug is by searching through
+ the history to find the exact commit that's to blame. Git bisect
+ can help you perform a binary search for that commit. It is
+ 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.
projects / git.git / commitdiff