diff options
| author | Junio C Hamano <junio@hera.kernel.org> | 2008-06-02 07:31:16 +0000 |
|---|---|---|
| committer | Junio C Hamano <junio@hera.kernel.org> | 2008-06-02 07:31:16 +0000 |
| commit | 9e1793f616e87f4cb87e970250caa7b5ee8ad313 (patch) | |
| tree | 8fbbdfbcf549bd60bd184ae0987347314be40d9e /gitcore-tutorial.html | |
| parent | 054ea0856e4bbd375c55e9f5960693e0da914411 (diff) | |
| download | git-htmldocs-9e1793f616e87f4cb87e970250caa7b5ee8ad313.tar.gz | |
Autogenerated HTML docs for v1.5.6-rc0-84-g06f60
Diffstat (limited to 'gitcore-tutorial.html')
| -rw-r--r-- | gitcore-tutorial.html | 1997 |
1 files changed, 1997 insertions, 0 deletions
diff --git a/gitcore-tutorial.html b/gitcore-tutorial.html new file mode 100644 index 000000000..58468ee66 --- /dev/null +++ b/gitcore-tutorial.html @@ -0,0 +1,1997 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
+ "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+<meta name="generator" content="AsciiDoc 7.0.2" />
+<style type="text/css">
+/* Debug borders */
+p, li, dt, dd, div, pre, h1, h2, h3, h4, h5, h6 {
+/*
+ border: 1px solid red;
+*/
+}
+
+body {
+ margin: 1em 5% 1em 5%;
+}
+
+a { color: blue; }
+a:visited { color: fuchsia; }
+
+em {
+ font-style: italic;
+}
+
+strong {
+ font-weight: bold;
+}
+
+tt {
+ color: navy;
+}
+
+h1, h2, h3, h4, h5, h6 {
+ color: #527bbd;
+ font-family: sans-serif;
+ margin-top: 1.2em;
+ margin-bottom: 0.5em;
+ line-height: 1.3;
+}
+
+h1 {
+ border-bottom: 2px solid silver;
+}
+h2 {
+ border-bottom: 2px solid silver;
+ padding-top: 0.5em;
+}
+
+div.sectionbody {
+ font-family: serif;
+ margin-left: 0;
+}
+
+hr {
+ border: 1px solid silver;
+}
+
+p {
+ margin-top: 0.5em;
+ margin-bottom: 0.5em;
+}
+
+pre {
+ padding: 0;
+ margin: 0;
+}
+
+span#author {
+ color: #527bbd;
+ font-family: sans-serif;
+ font-weight: bold;
+ font-size: 1.2em;
+}
+span#email {
+}
+span#revision {
+ font-family: sans-serif;
+}
+
+div#footer {
+ font-family: sans-serif;
+ font-size: small;
+ border-top: 2px solid silver;
+ padding-top: 0.5em;
+ margin-top: 4.0em;
+}
+div#footer-text {
+ float: left;
+ padding-bottom: 0.5em;
+}
+div#footer-badges {
+ float: right;
+ padding-bottom: 0.5em;
+}
+
+div#preamble,
+div.tableblock, div.imageblock, div.exampleblock, div.verseblock,
+div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
+div.admonitionblock {
+ margin-right: 10%;
+ margin-top: 1.5em;
+ margin-bottom: 1.5em;
+}
+div.admonitionblock {
+ margin-top: 2.5em;
+ margin-bottom: 2.5em;
+}
+
+div.content { /* Block element content. */
+ padding: 0;
+}
+
+/* Block element titles. */
+div.title, caption.title {
+ font-family: sans-serif;
+ font-weight: bold;
+ text-align: left;
+ margin-top: 1.0em;
+ margin-bottom: 0.5em;
+}
+div.title + * {
+ margin-top: 0;
+}
+
+td div.title:first-child {
+ margin-top: 0.0em;
+}
+div.content div.title:first-child {
+ margin-top: 0.0em;
+}
+div.content + div.title {
+ margin-top: 0.0em;
+}
+
+div.sidebarblock > div.content {
+ background: #ffffee;
+ border: 1px solid silver;
+ padding: 0.5em;
+}
+
+div.listingblock > div.content {
+ border: 1px solid silver;
+ background: #f4f4f4;
+ padding: 0.5em;
+}
+
+div.quoteblock > div.content {
+ padding-left: 2.0em;
+}
+div.quoteblock .attribution {
+ text-align: right;
+}
+
+div.admonitionblock .icon {
+ vertical-align: top;
+ font-size: 1.1em;
+ font-weight: bold;
+ text-decoration: underline;
+ color: #527bbd;
+ padding-right: 0.5em;
+}
+div.admonitionblock td.content {
+ padding-left: 0.5em;
+ border-left: 2px solid silver;
+}
+
+div.exampleblock > div.content {
+ border-left: 2px solid silver;
+ padding: 0.5em;
+}
+
+div.verseblock div.content {
+ white-space: pre;
+}
+
+div.imageblock div.content { padding-left: 0; }
+div.imageblock img { border: 1px solid silver; }
+span.image img { border-style: none; }
+
+dl {
+ margin-top: 0.8em;
+ margin-bottom: 0.8em;
+}
+dt {
+ margin-top: 0.5em;
+ margin-bottom: 0;
+ font-style: italic;
+}
+dd > *:first-child {
+ margin-top: 0;
+}
+
+ul, ol {
+ list-style-position: outside;
+}
+ol.olist2 {
+ list-style-type: lower-alpha;
+}
+
+div.tableblock > table {
+ border-color: #527bbd;
+ border-width: 3px;
+}
+thead {
+ font-family: sans-serif;
+ font-weight: bold;
+}
+tfoot {
+ font-weight: bold;
+}
+
+div.hlist {
+ margin-top: 0.8em;
+ margin-bottom: 0.8em;
+}
+td.hlist1 {
+ vertical-align: top;
+ font-style: italic;
+ padding-right: 0.8em;
+}
+td.hlist2 {
+ vertical-align: top;
+}
+
+@media print {
+ div#footer-badges { display: none; }
+}
+include::./stylesheets/xhtml11-manpage.css[]
+/* Workarounds for IE6's broken and incomplete CSS2. */
+
+div.sidebar-content {
+ background: #ffffee;
+ border: 1px solid silver;
+ padding: 0.5em;
+}
+div.sidebar-title, div.image-title {
+ font-family: sans-serif;
+ font-weight: bold;
+ margin-top: 0.0em;
+ margin-bottom: 0.5em;
+}
+
+div.listingblock div.content {
+ border: 1px solid silver;
+ background: #f4f4f4;
+ padding: 0.5em;
+}
+
+div.quoteblock-content {
+ padding-left: 2.0em;
+}
+
+div.exampleblock-content {
+ border-left: 2px solid silver;
+ padding-left: 0.5em;
+}
+</style>
+<title>gitcore-tutorial(7)</title>
+</head>
+<body>
+<div id="header">
+<h1>
+gitcore-tutorial(7) Manual Page
+</h1>
+<h2>NAME</h2>
+<div class="sectionbody">
+<p>gitcore-tutorial -
+ A git core tutorial for developers
+</p>
+</div>
+</div>
+<h2>SYNOPSIS</h2>
+<div class="sectionbody">
+<p>git *</p>
+</div>
+<h2>DESCRIPTION</h2>
+<div class="sectionbody">
+<p>This tutorial explains how to use the "core" git programs to set up and
+work with a git repository.</p>
+<p>If you just need to use git as a revision control system you may prefer
+to start with <a href="gittutorial.html">gittutorial(7)</a>[a tutorial introduction to git] or
+<a href="user-manual.html">the git user manual</a>.</p>
+<p>However, an understanding of these low-level tools can be helpful if
+you want to understand git's internals.</p>
+<p>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.</p>
+<div class="admonitionblock">
+<table><tr>
+<td class="icon">
+<div class="title">Note</div>
+</td>
+<td class="content">Deeper technical details are often marked as Notes, which you can
+skip on your first reading.</td>
+</tr></table>
+</div>
+</div>
+<h2>Creating a git repository</h2>
+<div class="sectionbody">
+<p>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.</p>
+<p>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 <tt>git-tutorial</tt>.
+To start up, create a subdirectory for it, change into that
+subdirectory, and initialize the git infrastructure with <tt>git-init</tt>:</p>
+<div class="listingblock">
+<div class="content">
+<pre><tt>$ mkdir git-tutorial
+$ cd git-tutorial
+$ git-init</tt></pre>
+</div></div>
+<p>to which git will reply</p>
+<div class="listingblock">
+<div class="content">
+<pre><tt>Initialized empty Git repository in .git/</tt></pre>
+</div></div>
+<p>which is just git's way of saying that you haven't been doing anything
+strange, and that it will have created a local <tt>.git</tt> directory setup for
+your new project. You will now have a <tt>.git</tt> directory, and you can
+inspect that with <tt>ls</tt>. For your new empty project, it should show you
+three entries, among other things:</p>
+<ul>
+<li>
+<p>
+a file called <tt>HEAD</tt>, that has <tt>ref: refs/heads/master</tt> in it.
+ This is similar to a symbolic link and points at
+ <tt>refs/heads/master</tt> relative to the <tt>HEAD</tt> file.
+</p>
+<p>Don't worry about the fact that the file that the <tt>HEAD</tt> link points to
+doesn't even exist yet — you haven't created the commit that will
+start your <tt>HEAD</tt> development branch yet.</p>
+</li>
+<li>
+<p>
+a subdirectory called <tt>objects</tt>, 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 <em>data</em> in your repository.
+</p>
+</li>
+<li>
+<p>
+a subdirectory called <tt>refs</tt>, which contains references to objects.
+</p>
+</li>
+</ul>
+<p>In particular, the <tt>refs</tt> subdirectory will contain two other
+subdirectories, named <tt>heads</tt> and <tt>tags</tt> respectively. They do
+exactly what their names imply: they contain references to any number
+of different <em>heads</em> of development (aka <em>branches</em>), and to any
+<em>tags</em> that you have created to name specific versions in your
+repository.</p>
+<p>One note: the special <tt>master</tt> head is the default branch, which is
+why the <tt>.git/HEAD</tt> file was created points to it even if it
+doesn't yet exist. Basically, the <tt>HEAD</tt> 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 <tt>master</tt> branch.</p>
+<p>However, this is only a convention, and you can name your branches
+anything you want, and don't have to ever even <em>have</em> a <tt>master</tt>
+branch. A number of the git tools will assume that <tt>.git/HEAD</tt> is
+valid, though.</p>
+<div class="admonitionblock">
+<table><tr>
+<td class="icon">
+<div class="title">Note</div>
+</td>
+<td class="content">An <em>object</em> is identified by its 160-bit SHA1 hash, aka <em>object name</em>,
+and a reference to an object is always the 40-byte hex
+representation of that SHA1 name. The files in the <tt>refs</tt>
+subdirectory are expected to contain these hex references
+(usually with a final <tt>'\n'</tt> at the end), and you should thus
+expect to see a number of 41-byte files containing these
+references in these <tt>refs</tt> subdirectories when you actually start
+populating your tree.</td>
+</tr></table>
+</div>
+<div class="admonitionblock">
+<table><tr>
+<td class="icon">
+<div class="title">Note</div>
+</td>
+<td class="content">An advanced user may want to take a look at the
+<a href="repository-layout.html">repository layout</a> document
+after finishing this tutorial.</td>
+</tr></table>
+</div>
+<p>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.</p>
+</div>
+<h2>Populating a git repository</h2>
+<div class="sectionbody">
+<p>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.</p>
+<p>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:</p>
+<div class="listingblock">
+<div class="content">
+<pre><tt>$ echo "Hello World" >hello
+$ echo "Silly example" >example</tt></pre>
+</div></div>
+<p>you have now created two files in your working tree (aka <em>working directory</em>),
+but to actually check in your hard work, you will have to go through two steps:</p>
+<ul>
+<li>
+<p>
+fill in the <em>index</em> file (aka <em>cache</em>) with the information about your
+ working tree state.
+</p>
+</li>
+<li>
+<p>
+commit that index file as an object.
+</p>
+</li>
+</ul>
+<p>The first step is trivial: when you want to tell git about any changes
+to your working tree, you use the <tt>git-update-index</tt> 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 <tt>--add</tt> flag (or removing an entry with the
+<tt>--remove</tt>) flag.</p>
+<p>So to populate the index with the two files you just created, you can do</p>
+<div class="listingblock">
+<div class="content">
+<pre><tt>$ git-update-index --add hello example</tt></pre>
+</div></div>
+<p>and you have now told git to track those two files.</p>
+<p>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</p>
+<div class="listingblock">
+<div class="content">
+<pre><tt>$ ls .git/objects/??/*</tt></pre>
+</div></div>
+<p>and see two files:</p>
+<div class="listingblock">
+<div class="content">
+<pre><tt>.git/objects/55/7db03de997c86a4a028e1ebd3a1ceb225be238
+.git/objects/f2/4c74a2e500f5ee1332c86b94199f52b1d1d962</tt></pre>
+</div></div>
+<p>which correspond with the objects with names of <tt>557db…</tt> and
+<tt>f24c7…</tt> respectively.</p>
+<p>If you want to, you can use <tt>git-cat-file</tt> to look at those objects, but
+you'll have to use the object name, not the filename of the object:</p>
+<div class="listingblock">
+<div class="content">
+<pre><tt>$ git-cat-file -t 557db03de997c86a4a028e1ebd3a1ceb225be238</tt></pre>
+</div></div>
+<p>where the <tt>-t</tt> tells <tt>git-cat-file</tt> to tell you what the "type" of the
+object is. git will tell you that you have a "blob" object (i.e., just a
+regular file), and you can see the contents with</p>
+<div class="listingblock">
+<div class="content">
+<pre><tt>$ git-cat-file "blob" 557db03</tt></pre>
+</div></div>
+<p>which will print out "Hello World". The object <tt>557db03</tt> is nothing
+more than the contents of your file <tt>hello</tt>.</p>
+<div class="admonitionblock">
+<table><tr>
+<td class="icon">
+<div class="title">Note</div>
+</td>
+<td class="content">Don't confuse that object with the file <tt>hello</tt> itself. The
+object is literally just those specific <strong>contents</strong> of the file, and
+however much you later change the contents in file <tt>hello</tt>, the object
+we just looked at will never change. Objects are immutable.</td>
+</tr></table>
+</div>
+<div class="admonitionblock">
+<table><tr>
+<td class="icon">
+<div class="title">Note</div>
+</td>
+<td class="content">The second example demonstrates that you can
+abbreviate the object name to only the first several
+hexadecimal digits in most places.</td>
+</tr></table>
+</div>
+<p>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 <tt>git-update-index</tt> did something magical, and
+actually saved away the contents of your files into the git object
+database.</p>
+<p>Updating the index did something else too: it created a <tt>.git/index</tt>
+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 <strong>told</strong> git about them.</p>
+<p>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.</p>
+<p>In particular, let's not even check in the two files into git yet, we'll
+start off by adding another line to <tt>hello</tt> first:</p>
+<div class="listingblock">
+<div class="content">
+<pre><tt>$ echo "It's a new day for git" >>hello</tt></pre>
+</div></div>
+<p>and you can now, since you told git about the previous state of <tt>hello</tt>, ask
+git what has changed in the tree compared to your old index, using the
+<tt>git-diff-files</tt> command:</p>
+<div class="listingblock">
+<div class="content">
+<pre><tt>$ git-diff-files</tt></pre>
+</div></div>
+<p>Oops. That wasn't very readable. It just spit out its own internal
+version of a <tt>diff</tt>, 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.</p>
+<p>To make it readable, we can tell git-diff-files to output the
+differences as a patch, using the <tt>-p</tt> flag:</p>
+<div class="listingblock">
+<div class="content">
+<pre><tt>$ 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</tt></pre>
+</div></div>
+<p>i.e. the diff of the change we caused by adding another line to <tt>hello</tt>.</p>
+<p>In other words, <tt>git-diff-files</tt> always shows us the difference between
+what is recorded in the index, and what is currently in the working
+tree. That's very useful.</p>
+<p>A common shorthand for <tt>git-diff-files -p</tt> is to just write <tt>git
+diff</tt>, which will do the same thing.</p>
+<div class="listingblock">
+<div class="content">
+<pre><tt>$ 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</tt></pre>
+</div></div>
+</div>
+<h2>Committing git state</h2>
+<div class="sectionbody">
+<p>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 <em>tree</em> object, and committing that <em>tree</em>
+object as a <em>commit</em> object together with an explanation of what the
+tree was all about, along with information of how we came to that state.</p>
+<p>Creating a tree object is trivial, and is done with <tt>git-write-tree</tt>.
+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:</p>
+<div class="listingblock">
+<div class="content">
+<pre><tt>$ git-write-tree</tt></pre>
+</div></div>
+<p>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</p>
+<div class="listingblock">
+<div class="content">
+<pre><tt>8988da15d077d4829fc51d8544c097def6644dbb</tt></pre>
+</div></div>
+<p>which is another incomprehensible object name. Again, if you want to,
+you can use <tt>git-cat-file -t 8988d...</tt> to see that this time the object
+is not a "blob" object, but a "tree" object (you can also use
+<tt>git-cat-file</tt> to actually output the raw object contents, but you'll see
+mainly a binary mess, so that's less interesting).</p>
+<p>However — normally you'd never use <tt>git-write-tree</tt> on its own, because
+normally you always commit a tree into a commit object using the
+<tt>git-commit-tree</tt> command. In fact, it's easier to not actually use
+<tt>git-write-tree</tt> on its own at all, but to just pass its result in as an
+argument to <tt>git-commit-tree</tt>.</p>
+<p><tt>git-commit-tree</tt> normally takes several arguments — it wants to know
+what the <em>parent</em> 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, <tt>git-commit-tree</tt> 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.</p>
+<p>And this is where we create the <tt>.git/refs/heads/master</tt> file
+which is pointed at by <tt>HEAD</tt>. This file is supposed to contain
+the reference to the top-of-tree of the master branch, and since
+that's exactly what <tt>git-commit-tree</tt> spits out, we can do this
+all with a sequence of simple shell commands:</p>
+<div class="listingblock">
+<div class="content">
+<pre><tt>$ tree=$(git-write-tree)
+$ commit=$(echo 'Initial commit' | git-commit-tree $tree)
+$ git-update-ref HEAD $commit</tt></pre>
+</div></div>
+<p>In this case this creates a totally new commit that is not related to
+anything else. Normally you do this only <strong>once</strong> for a project ever, and
+all later commits will be parented on top of an earlier commit.</p>
+<p>Again, normally you'd never actually do this by hand. There is a
+helpful script called <tt>git commit</tt> that will do all of this for you. So
+you could have just written <tt>git commit</tt>
+instead, and it would have done the above magic scripting for you.</p>
+</div>
+<h2>Making a change</h2>
+<div class="sectionbody">
+<p>Remember how we did the <tt>git-update-index</tt> on file <tt>hello</tt> and then we
+changed <tt>hello</tt> afterward, and could compare the new state of <tt>hello</tt> with the
+state we saved in the index file?</p>
+<p>Further, remember how I said that <tt>git-write-tree</tt> writes the contents
+of the <strong>index</strong> file to the tree, and thus what we just committed was in
+fact the <strong>original</strong> contents of the file <tt>hello</tt>, 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.</p>
+<p>As before, if we do <tt>git-diff-files -p</tt> 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:
+<tt>git-diff-index</tt>.</p>
+<p>Unlike <tt>git-diff-files</tt>, which showed the difference between the index
+file and the working tree, <tt>git-diff-index</tt> shows the differences
+between a committed <strong>tree</strong> and either the index file or the working
+tree. In other words, <tt>git-diff-index</tt> 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.</p>
+<p>But now we can do</p>
+<div class="listingblock">
+<div class="content">
+<pre><tt>$ git-diff-index -p HEAD</tt></pre>
+</div></div>
+<p>(where <tt>-p</tt> has the same meaning as it did in <tt>git-diff-files</tt>), 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.</p>
+<p>Again, because this is a common operation, you can also just shorthand
+it with</p>
+<div class="listingblock">
+<div class="content">
+<pre><tt>$ git diff HEAD</tt></pre>
+</div></div>
+<p>which ends up doing the above for you.</p>
+<p>In other words, <tt>git-diff-index</tt> normally compares a tree against the
+working tree, but when given the <tt>--cached</tt> 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 <tt>git-diff-index --cached -p HEAD</tt> should thus return
+an empty set of differences, and that's exactly what it does.</p>
+<div class="admonitionblock">
+<table><tr>
+<td class="icon">
+<div class="title">Note</div>
+</td>
+<td class="content">
+<p><tt>git-diff-index</tt> 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") <strong>always</strong> comes from the index file,
+regardless of whether the <tt>--cached</tt> flag is used or not. The <tt>--cached</tt>
+flag really only determines whether the file <strong>contents</strong> to be compared
+come from the working tree or not.</p>
+<p>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 <strong>looking</strong> for files to compare, it
+expects you to tell it what the files are, and that's what the index
+is there for.</p>
+</td>
+</tr></table>
+</div>
+<p>However, our next step is to commit the <strong>change</strong> 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:</p>
+<div class="listingblock">
+<div class="content">
+<pre><tt>$ git-update-index hello</tt></pre>
+</div></div>
+<p>(note how we didn't need the <tt>--add</tt> flag this time, since git knew
+about the file already).</p>
+<p>Note what happens to the different <tt>git-diff-*</tt> versions here. After
+we've updated <tt>hello</tt> in the index, <tt>git-diff-files -p</tt> now shows no
+differences, but <tt>git-diff-index -p HEAD</tt> still *does* show that the
+current state is different from the state we committed. In fact, now
+<tt>git-diff-index</tt> shows the same difference whether we use the <tt>--cached</tt>
+flag or not, since now the index is coherent with the working tree.</p>
+<p>Now, since we've updated <tt>hello</tt> 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 <tt>-p HEAD</tt> flag to
+tell commit that the HEAD was the <strong>parent</strong> 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:</p>
+<div class="listingblock">
+<div class="content">
+<pre><tt>$ git commit</tt></pre>
+</div></div>
+<p>which starts an editor for you to write the commit message and tells you
+a bit about what you have done.</p>
+<p>Write whatever message you want, and all the lines that start with <em>#</em>
+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 <tt>git commit</tt> will commit
+the change for you.</p>
+<p>You've now made your first real git commit. And if you're interested in
+looking at what <tt>git commit</tt> 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 (<tt>git-commit</tt>).</p>
+</div>
+<h2>Inspecting Changes</h2>
+<div class="sectionbody">
+<p>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
+<tt>diff</tt> family, namely <tt>git-diff-tree</tt>.</p>
+<p><tt>git-diff-tree</tt> 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</p>
+<div class="listingblock">
+<div class="content">
+<pre><tt>$ git-diff-tree -p HEAD</tt></pre>
+</div></div>
+<p>(again, <tt>-p</tt> means to show the difference as a human-readable patch),
+and it will show what the last commit (in <tt>HEAD</tt>) actually changed.</p>
+<div class="admonitionblock">
+<table><tr>
+<td class="icon">
+<div class="title">Note</div>
+</td>
+<td class="content">
+<p>Here is an ASCII art by Jon Loeliger that illustrates how
+various diff-* commands compare things.</p>
+<div class="literalblock">
+<div class="content">
+<pre><tt> diff-tree
+ +----+
+ | |
+ | |
+ V V
+ +-----------+
+ | Object DB |
+ | Backing |
+ | Store |
+ +-----------+
+ ^ ^
+ | |
+ | | diff-index --cached
+ | |
+diff-index | V
+ | +-----------+
+ | | Index |
+ | | "cache" |
+ | +-----------+
+ | ^
+ | |
+ | | diff-files
+ | |
+ V V
+ +-----------+
+ | Working |
+ | Directory |
+ +-----------+</tt></pre>
+</div></div>
+</td>
+</tr></table>
+</div>
+<p>More interestingly, you can also give <tt>git-diff-tree</tt> the <tt>--pretty</tt> 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.</p>
+<p>In fact, together with the <tt>git-rev-list</tt> program (which generates a
+list of revisions), <tt>git-diff-tree</tt> ends up being a veritable fount of
+changes. A trivial (but very useful) script called <tt>git-whatchanged</tt> is
+included with git which does exactly this, and shows a log of recent
+activities.</p>
+<p>To see the whole history of our pitiful little git-tutorial project, you
+can do</p>
+<div class="listingblock">
+<div class="content">
+<pre><tt>$ git log</tt></pre>
+</div></div>
+<p>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)</p>
+<div class="listingblock">
+<div class="content">
+<pre><tt>$ git-whatchanged -p</tt></pre>
+</div></div>
+<p>and you will see exactly what has changed in the repository over its
+short history.</p>
+<div class="admonitionblock">
+<table><tr>
+<td class="icon">
+<div class="title">Note</div>
+</td>
+<td class="content">When using the above two commands, the initial commit will be shown.
+If this is a problem because it is huge, you can hide it by setting
+the log.showroot configuration variable to false. Having this, you
+can still show it for each command just adding the <tt>--root</tt> option,
+which is a flag for <tt>git-diff-tree</tt> accepted by both commands.</td>
+</tr></table>
+</div>
+<p>With that, you should now be having some inkling of what git does, and
+can explore on your own.</p>
+<div class="admonitionblock">
+<table><tr>
+<td class="icon">
+<div class="title">Note</div>
+</td>
+<td class="content">Most likely, you are not directly using the core
+git Plumbing commands, but using Porcelain such as <tt>git-add</tt>, `git-rm'
+and `git-commit'.</td>
+</tr></table>
+</div>
+</div>
+<h2>Tagging a version</h2>
+<div class="sectionbody">
+<p>In git, there are two kinds of tags, a "light" one, and an "annotated tag".</p>
+<p>A "light" tag is technically nothing more than a branch, except we put
+it in the <tt>.git/refs/tags/</tt> subdirectory instead of calling it a <tt>head</tt>.
+So the simplest form of tag involves nothing more than</p>
+<div class="listingblock">
+<div class="content">
+<pre><tt>$ git tag my-first-tag</tt></pre>
+</div></div>
+<p>which just writes the current <tt>HEAD</tt> into the <tt>.git/refs/tags/my-first-tag</tt>
+file, after which point you can then use this symbolic name for that
+particular state. You can, for example, do</p>
+<div class="listingblock">
+<div class="content">
+<pre><tt>$ git diff my-first-tag</tt></pre>
+</div></div>
+<p>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.</p>
+<p>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 <tt>-a</tt> or
+<tt>-s</tt> flag to <tt>git tag</tt>:</p>
+<div class="listingblock">
+<div class="content">
+<pre><tt>$ git tag -s <tagname></tt></pre>
+</div></div>
+<p>which will sign the current <tt>HEAD</tt> (but you can also give it another
+argument that specifies the thing to tag, i.e., you could have tagged the
+current <tt>mybranch</tt> point by using <tt>git tag <tagname> mybranch</tt>).</p>
+<p>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.</p>
+</div>
+<h2>Copying repositories</h2>
+<div class="sectionbody">
+<p>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 <strong>is</strong> the
+working tree, with the local git information hidden in the <tt>.git</tt>
+subdirectory. There is nothing else. What you see is what you got.</p>
+<div class="admonitionblock">
+<table><tr>
+<td class="icon">
+<div class="title">Note</div>
+</td>
+<td class="content">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.</td>
+</tr></table>
+</div>
+<p>This has two implications:</p>
+<ul>
+<li>
+<p>
+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
+</p>
+<div class="listingblock">
+<div class="content">
+<pre><tt>$ rm -rf git-tutorial</tt></pre>
+</div></div>
+<p>and it will be gone. There's no external repository, and there's no
+history outside the project you created.</p>
+</li>
+<li>
+<p>
+if you want to move or duplicate a git repository, you can do so. There
+ is <tt>git clone</tt> 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
+ <tt>cp -a git-tutorial new-git-tutorial</tt>.
+</p>
+<p>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 <tt>cp -a</tt> to create a new copy, you'll want to do</p>
+<div class="listingblock">
+<div class="content">
+<pre><tt>$ git-update-index --refresh</tt></pre>
+</div></div>
+<p>in the new repository to make sure that the index file is up-to-date.</p>
+</li>
+</ul>
+<p>Note that the second point is true even across machines. You can
+duplicate a remote git repository with <strong>any</strong> regular copy mechanism, be it
+<tt>scp</tt>, <tt>rsync</tt> or <tt>wget</tt>.</p>
+<p>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 <strong>what</strong> they've done and not yet checked in),
+so usually you'll precede the <tt>git-update-index</tt> with a</p>
+<div class="listingblock">
+<div class="content">
+<pre><tt>$ git-read-tree --reset HEAD
+$ git-update-index --refresh</tt></pre>
+</div></div>
+<p>which will force a total index re-build from the tree pointed to by <tt>HEAD</tt>.
+It resets the index contents to <tt>HEAD</tt>, and then the <tt>git-update-index</tt>
+makes sure to match up all index entries with the checked-out files.
+If the original repository had uncommitted changes in its
+working tree, <tt>git-update-index --refresh</tt> notices them and
+tells you they need to be updated.</p>
+<p>The above can also be written as simply</p>
+<div class="listingblock">
+<div class="content">
+<pre><tt>$ git reset</tt></pre>
+</div></div>
+<p>and in fact a lot of the common git command combinations can be scripted
+with the <tt>git xyz</tt> interfaces. You can learn things by just looking
+at what the various git scripts do. For example, <tt>git reset</tt> used to be
+the above two lines implemented in <tt>git-reset</tt>, but some things like
+<tt>git status</tt> and <tt>git commit</tt> are slightly more complex scripts around
+the basic git commands.</p>
+<p>Many (most?) public remote repositories will not contain any of
+the checked out files or even an index file, and will <strong>only</strong> contain the
+actual core git files. Such a repository usually doesn't even have the
+<tt>.git</tt> subdirectory, but has all the git files directly in the
+repository.</p>
+<p>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 <tt>.git</tt> directory. For example, to
+create your own copy of the git repository, you'd do the following</p>
+<div class="listingblock">
+<div class="content">
+<pre><tt>$ mkdir my-git
+$ cd my-git
+$ rsync -rL rsync://rsync.kernel.org/pub/scm/git/git.git/ .git</tt></pre>
+</div></div>
+<p>followed by</p>
+<div class="listingblock">
+<div class="content">
+<pre><tt>$ git-read-tree HEAD</tt></pre>
+</div></div>
+<p>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</p>
+<div class="listingblock">
+<div class="content">
+<pre><tt>$ git-checkout-index -u -a</tt></pre>
+</div></div>
+<p>where the <tt>-u</tt> 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
+<tt>-a</tt> 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 <tt>-f</tt>
+flag first, to tell git-checkout-index to <strong>force</strong> overwriting of any old
+files).</p>
+<p>Again, this can all be simplified with</p>
+<div class="listingblock">
+<div class="content">
+<pre><tt>$ git clone rsync://rsync.kernel.org/pub/scm/git/git.git/ my-git
+$ cd my-git
+$ git checkout</tt></pre>
+</div></div>
+<p>which will end up doing all of the above for you.</p>
+<p>You have now successfully copied somebody else's (mine) remote
+repository, and checked it out.</p>
+</div>
+<h2>Creating a new branch</h2>
+<div class="sectionbody">
+<p>Branches in git are really nothing more than pointers into the git
+object database from within the <tt>.git/refs/</tt> subdirectory, and as we
+already discussed, the <tt>HEAD</tt> branch is nothing but a symlink to one of
+these object pointers.</p>
+<p>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 <tt>.git/refs/heads/</tt>. You can use any filename you
+want (and indeed, subdirectories), but the convention is that the
+"normal" branch is called <tt>master</tt>. That's just a convention, though,
+and nothing enforces it.</p>
+<p>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:</p>
+<div class="listingblock">
+<div class="content">
+<pre><tt>$ git checkout -b mybranch</tt></pre>
+</div></div>
+<p>will create a new branch based at the current <tt>HEAD</tt> position, and switch
+to it.</p>
+<div class="admonitionblock">
+<table><tr>
+<td class="icon">
+<div class="title">Note</div>
+</td>
+<td class="content">
+<p>If you make the decision to start your new branch at some
+other point in the history than the current <tt>HEAD</tt>, you can do so by
+just telling <tt>git checkout</tt> what the base of the checkout would be.
+In other words, if you have an earlier tag or branch, you'd just do</p>
+<div class="listingblock">
+<div class="content">
+<pre><tt>$ git checkout -b mybranch earlier-commit</tt></pre>
+</div></div>
+<p>and it would create the new branch <tt>mybranch</tt> at the earlier commit,
+and check out the state at that time.</p>
+</td>
+</tr></table>
+</div>
+<p>You can always just jump back to your original <tt>master</tt> branch by doing</p>
+<div class="listingblock">
+<div class="content">
+<pre><tt>$ git checkout master</tt></pre>
+</div></div>
+<p>(or any other branch-name, for that matter) and if you forget which
+branch you happen to be on, a simple</p>
+<div class="listingblock">
+<div class="content">
+<pre><tt>$ cat .git/HEAD</tt></pre>
+</div></div>
+<p>will tell you where it's pointing. To get the list of branches
+you have, you can say</p>
+<div class="listingblock">
+<div class="content">
+<pre><tt>$ git branch</tt></pre>
+</div></div>
+<p>which used to be nothing more than a simple script around <tt>ls .git/refs/heads</tt>.
+There will be an asterisk in front of the branch you are currently on.</p>
+<p>Sometimes you may wish to create a new branch _without_ actually
+checking it out and switching to it. If so, just use the command</p>
+<div class="listingblock">
+<div class="content">
+<pre><tt>$ git branch <branchname> [startingpoint]</tt></pre>
+</div></div>
+<p>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 <tt>git checkout</tt>
+with the branchname as the argument.</p>
+</div>
+<h2>Merging two branches</h2>
+<div class="sectionbody">
+<p>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 <tt>mybranch</tt> that started out
+being the same as the original <tt>master</tt> branch, let's make sure we're in
+that branch, and do some work there.</p>
+<div class="listingblock">
+<div class="content">
+<pre><tt>$ git checkout mybranch
+$ echo "Work, work, work" >>hello
+$ git commit -m "Some work." -i hello</tt></pre>
+</div></div>
+<p>Here, we just added another line to <tt>hello</tt>, and we used a shorthand for
+doing both <tt>git-update-index hello</tt> and <tt>git commit</tt> by just giving the
+filename directly to <tt>git commit</tt>, with an <tt>-i</tt> flag (it tells
+git to <em>include</em> that file in addition to what you have done to
+the index file so far when making the commit). The <tt>-m</tt> flag is to give the
+commit log message from the command line.</p>
+<p>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:</p>
+<div class="listingblock">
+<div class="content">
+<pre><tt>$ git checkout master</tt></pre>
+</div></div>
+<p>Here, take a moment to look at the contents of <tt>hello</tt>, and notice how they
+don't contain the work we just did in <tt>mybranch</tt> — because that work
+hasn't happened in the <tt>master</tt> branch at all. Then do</p>
+<div class="listingblock">
+<div class="content">
+<pre><tt>$ echo "Play, play, play" >>hello
+$ echo "Lots of fun" >>example
+$ git commit -m "Some fun." -i hello example</tt></pre>
+</div></div>
+<p>since the master branch is obviously in a much better mood.</p>
+<p>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:</p>
+<div class="listingblock">
+<div class="content">
+<pre><tt>$ gitk --all</tt></pre>
+</div></div>
+<p>will show you graphically both of your branches (that's what the <tt>--all</tt>
+means: normally it will just show you your current <tt>HEAD</tt>) and their
+histories. You can also see exactly how they came to be from a common
+source.</p>
+<p>Anyway, let's exit <tt>gitk</tt> (<tt>^Q</tt> or the File menu), and decide that we want
+to merge the work we did on the <tt>mybranch</tt> branch into the <tt>master</tt>
+branch (which is currently our <tt>HEAD</tt> too). To do that, there's a nice
+script called <tt>git merge</tt>, which wants to know which branches you want
+to resolve and what the merge is all about:</p>
+<div class="listingblock">
+<div class="content">
+<pre><tt>$ git merge -m "Merge work in mybranch" mybranch</tt></pre>
+</div></div>
+<p>where the first argument is going to be used as the commit message if
+the merge can be resolved automatically.</p>
+<p>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 <tt>example</tt>
+file, which had no differences in the <tt>mybranch</tt> branch), and say:</p>
+<div class="listingblock">
+<div class="content">
+<pre><tt> Auto-merging hello
+ CONFLICT (content): Merge conflict in hello
+ Automatic merge failed; fix up by hand</tt></pre>
+</div></div>
+<p>It tells you that it did an "Automatic merge", which
+failed due to conflicts in <tt>hello</tt>.</p>
+<p>Not to worry. It left the (trivial) conflict in <tt>hello</tt> in the same form you
+should already be well used to if you've ever used CVS, so let's just
+open <tt>hello</tt> in our editor (whatever that may be), and fix it up somehow.
+I'd suggest just making it so that <tt>hello</tt> contains all four lines:</p>
+<div class="listingblock">
+<div class="content">
+<pre><tt>Hello World
+It's a new day for git
+Play, play, play
+Work, work, work</tt></pre>
+</div></div>
+<p>and once you're happy with your manual merge, just do a</p>
+<div class="listingblock">
+<div class="content">
+<pre><tt>$ git commit -i hello</tt></pre>
+</div></div>
+<p>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.</p>
+<p>After you're done, start up <tt>gitk --all</tt> to see graphically what the
+history looks like. Notice that <tt>mybranch</tt> still exists, and you can
+switch to it, and continue to work with it if you want to. The
+<tt>mybranch</tt> branch will not contain the merge, but next time you merge it
+from the <tt>master</tt> branch, git will know how you merged it, so you'll not
+have to do _that_ merge again.</p>
+<p>Another useful tool, especially if you do not always work in X-Window
+environment, is <tt>git show-branch</tt>.</p>
+<div class="listingblock">
+<div class="content">
+<pre><tt>$ git-show-branch --topo-order --more=1 master mybranch
+* [master] Merge work in mybranch
+ ! [mybranch] Some work.
+--
+- [master] Merge work in mybranch
+*+ [mybranch] Some work.
+* [master^] Some fun.</tt></pre>
+</div></div>
+<p>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 <tt>master</tt> branch
+(notice the asterisk <tt>*</tt> character), and the first column for
+the later output lines is used to show commits contained in the
+<tt>master</tt> branch, and the second column for the <tt>mybranch</tt>
+branch. Three commits are shown along with their log messages.
+All of them have non blank characters in the first column (<tt>*</tt>
+shows an ordinary commit on the current branch, <tt>-</tt> is a merge commit), which
+means they are now part of the <tt>master</tt> branch. Only the "Some
+work" commit has the plus <tt>+</tt> character in the second column,
+because <tt>mybranch</tt> 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, <em>master</em> and <em>mybranch</em>
+are branch heads. <em>master^</em> is the first parent of <em>master</em>
+branch head. Please see <em>git-rev-parse</em> documentation if you
+see more complex cases.</p>
+<div class="admonitionblock">
+<table><tr>
+<td class="icon">
+<div class="title">Note</div>
+</td>
+<td class="content">Without the <em>--more=1</em> option, <em>git-show-branch</em> would not output the
+<em>[master^]</em> commit, as <em>[mybranch]</em> commit is a common ancestor of
+both <em>master</em> and <em>mybranch</em> tips. Please see <em>git-show-branch</em>
+documentation for details.</td>
+</tr></table>
+</div>
+<div class="admonitionblock">
+<table><tr>
+<td class="icon">
+<div class="title">Note</div>
+</td>
+<td class="content">If there were more commits on the <em>master</em> branch after the merge, the
+merge commit itself would not be shown by <em>git-show-branch</em> by
+default. You would need to provide <em>--sparse</em> option to make the
+merge commit visible in this case.</td>
+</tr></table>
+</div>
+<p>Now, let's pretend you are the one who did all the work in
+<tt>mybranch</tt>, and the fruit of your hard work has finally been merged
+to the <tt>master</tt> branch. Let's go back to <tt>mybranch</tt>, and run
+<tt>git merge</tt> to get the "upstream changes" back to your branch.</p>
+<div class="listingblock">
+<div class="content">
+<pre><tt>$ git checkout mybranch
+$ git merge -m "Merge upstream changes." master</tt></pre>
+</div></div>
+<p>This outputs something like this (the actual commit object names
+would be different)</p>
+<div class="listingblock">
+<div class="content">
+<pre><tt>Updating from ae3a2da... to a80b4aa....
+Fast forward
+ example | 1 +
+ hello | 1 +
+ 2 files changed, 2 insertions(+), 0 deletions(-)</tt></pre>
+</div></div>
+<p>Because your branch did not contain anything more than what are
+already merged into the <tt>master</tt> branch, the merge operation did
+not actually do a merge. Instead, it just updated the top of
+the tree of your branch to that of the <tt>master</tt> branch. This is
+often called <em>fast forward</em> merge.</p>
+<p>You can run <tt>gitk --all</tt> again to see how the commit ancestry
+looks like, or run <tt>show-branch</tt>, which tells you this.</p>
+<div class="listingblock">
+<div class="content">
+<pre><tt>$ git show-branch master mybranch
+! [master] Merge work in mybranch
+ * [mybranch] Merge work in mybranch
+--
+-- [master] Merge work in mybranch</tt></pre>
+</div></div>
+</div>
+<h2>Merging external work</h2>
+<div class="sectionbody">
+<p>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 <tt>git merge</tt>. 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 <tt>git merge</tt>.</p>
+<p>Fetching from a remote repository is done by, unsurprisingly,
+<tt>git fetch</tt>:</p>
+<div class="listingblock">
+<div class="content">
+<pre><tt>$ git fetch <remote-repository></tt></pre>
+</div></div>
+<p>One of the following transports can be used to name the
+repository to download from:</p>
+<dl>
+<dt>
+Rsync
+</dt>
+<dd>
+<p>
+ <tt>rsync://remote.machine/path/to/repo.git/</tt>
+</p>
+<p>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 <tt>rsync</tt>
+transport. Most notably, it could update the files under
+<tt>refs/</tt> which holds the object name of the topmost commits
+before uploading the files in <tt>objects/</tt> — 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.</p>
+</dd>
+<dt>
+SSH
+</dt>
+<dd>
+<p>
+ <tt>remote.machine:/path/to/repo.git/</tt> or
+</p>
+<p><tt>ssh://remote.machine/path/to/repo.git/</tt></p>
+<p>This transport can be used for both uploading and downloading,
+and requires you to have a log-in privilege over <tt>ssh</tt> 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.</p>
+</dd>
+<dt>
+Local directory
+</dt>
+<dd>
+<p>
+ <tt>/path/to/repo.git/</tt>
+</p>
+<p>This transport is the same as SSH transport but uses <tt>sh</tt> to run
+both ends on the local machine instead of running other end on
+the remote machine via <tt>ssh</tt>.</p>
+</dd>
+<dt>
+git Native
+</dt>
+<dd>
+<p>
+ <tt>git://remote.machine/path/to/repo.git/</tt>
+</p>
+<p>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.</p>
+</dd>
+<dt>
+HTTP(S)
+</dt>
+<dd>
+<p>
+ <tt>http://remote.machine/path/to/repo.git/</tt>
+</p>
+<p>Downloader from http and https URL
+first obtains the topmost commit object name from the remote site
+by looking at the specified refname under <tt>repo.git/refs/</tt> directory,
+and then tries to obtain the
+commit object by downloading from <tt>repo.git/objects/xx/xxx...</tt>
+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 behavior, they are
+sometimes also called <em>commit walkers</em>.</p>
+<p>The <em>commit walkers</em> are sometimes also called <em>dumb
+transports</em>, 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 <tt>git-update-server-info</tt>
+to help dumb transport downloaders.</p>
+</dd>
+</dl>
+<p>Once you fetch from the remote repository, you <tt>merge</tt> that
+with your current branch.</p>
+<p>However — it's such a common thing to <tt>fetch</tt> and then
+immediately <tt>merge</tt>, that it's called <tt>git pull</tt>, and you can
+simply do</p>
+<div class="listingblock">
+<div class="content">
+<pre><tt>$ git pull <remote-repository></tt></pre>
+</div></div>
+<p>and optionally give a branch-name for the remote end as a second
+argument.</p>
+<div class="admonitionblock">
+<table><tr>
+<td class="icon">
+<div class="title">Note</div>
+</td>
+<td class="content">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 <tt>git pull</tt>, just like
+you merge between branches. The advantage of this approach is
+that it lets you keep a set of files for each <tt>branch</tt> 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.</td>
+</tr></table>
+</div>
+<p>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 the local repository's config file
+like this:</p>
+<div class="listingblock">
+<div class="content">
+<pre><tt>$ git config remote.linus.url http://www.kernel.org/pub/scm/git/git.git/</tt></pre>
+</div></div>
+<p>and use the "linus" keyword with <tt>git pull</tt> instead of the full URL.</p>
+<p>Examples.</p>
+<ol>
+<li>
+<p>
+<tt>git pull linus</tt>
+</p>
+</li>
+<li>
+<p>
+<tt>git pull linus tag v0.99.1</tt>
+</p>
+</li>
+</ol>
+<p>the above are equivalent to:</p>
+<ol>
+<li>
+<p>
+<tt>git pull http://www.kernel.org/pub/scm/git/git.git/ HEAD</tt>
+</p>
+</li>
+<li>
+<p>
+<tt>git pull http://www.kernel.org/pub/scm/git/git.git/ tag v0.99.1</tt>
+</p>
+</li>
+</ol>
+</div>
+<h2>How does the merge work?</h2>
+<div class="sectionbody">
+<p>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.</p>
+<p>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:</p>
+<div class="listingblock">
+<div class="content">
+<pre><tt>$ git show-branch --more=2 master mybranch
+! [master] Merge work in mybranch
+ * [mybranch] Merge work in mybranch
+--
+-- [master] Merge work in mybranch
++* [master^2] Some work.
++* [master^] Some fun.</tt></pre>
+</div></div>
+<p>Remember, before running <tt>git merge</tt>, our <tt>master</tt> head was at
+"Some fun." commit, while our <tt>mybranch</tt> head was at "Some
+work." commit.</p>
+<div class="listingblock">
+<div class="content">
+<pre><tt>$ git checkout mybranch
+$ git reset --hard master^2
+$ git checkout master
+$ git reset --hard master^</tt></pre>
+</div></div>
+<p>After rewinding, the commit structure should look like this:</p>
+<div class="listingblock">
+<div class="content">
+<pre><tt>$ git show-branch
+* [master] Some fun.
+ ! [mybranch] Some work.
+--
+ + [mybranch] Some work.
+* [master] Some fun.
+*+ [mybranch^] New day.</tt></pre>
+</div></div>
+<p>Now we are ready to experiment with the merge by hand.</p>
+<p><tt>git merge</tt> command, when merging two branches, uses 3-way merge
+algorithm. First, it finds the common ancestor between them.
+The command it uses is <tt>git-merge-base</tt>:</p>
+<div class="listingblock">
+<div class="content">
+<pre><tt>$ mb=$(git-merge-base HEAD mybranch)</tt></pre>
+</div></div>
+<p>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. By the way, the common
+ancestor commit is the "New day." commit in this case. You can
+tell it by:</p>
+<div class="listingblock">
+<div class="content">
+<pre><tt>$ git-name-rev $mb
+my-first-tag</tt></pre>
+</div></div>
+<p>After finding out a common ancestor commit, the second step is
+this:</p>
+<div class="listingblock">
+<div class="content">
+<pre><tt>$ git-read-tree -m -u $mb HEAD mybranch</tt></pre>
+</div></div>
+<p>This is the same <tt>git-read-tree</tt> command we have already seen,
+but it takes three trees, unlike previous examples. This reads
+the contents of each tree into different <em>stage</em> in the index
+file (the first tree goes to stage 1, the second to stage 2,
+etc.). After reading three trees into three stages, the paths
+that are the same in all three stages are <em>collapsed</em> 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).</p>
+<p>After <em>collapsing</em> 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:</p>
+<div class="listingblock">
+<div class="content">
+<pre><tt>$ git-ls-files --stage
+100644 7f8b141b65fdcee47321e399a2598a235a032422 0 example
+100644 263414f423d0e4d70dae8fe53fa34614ff3e2860 1 hello
+100644 06fa6a24256dc7e560efa5687fa84b51f0263c3a 2 hello
+100644 cc44c73eb783565da5831b4d820c962954019b69 3 hello</tt></pre>
+</div></div>
+<p>In our example of only two files, we did not have unchanged
+files so only <em>example</em> resulted in collapsing, but in real-life
+large projects, only small number of files change in one commit,
+and this <em>collapsing</em> tends to trivially merge most of the paths
+fairly quickly, leaving only a handful the real changes in non-zero
+stages.</p>
+<p>To look at only non-zero stages, use <tt>--unmerged</tt> flag:</p>
+<div class="listingblock">
+<div class="content">
+<pre><tt>$ git-ls-files --unmerged
+100644 263414f423d0e4d70dae8fe53fa34614ff3e2860 1 hello
+100644 06fa6a24256dc7e560efa5687fa84b51f0263c3a 2 hello
+100644 cc44c73eb783565da5831b4d820c962954019b69 3 hello</tt></pre>
+</div></div>
+<p>The next step of merging is to merge these three versions of the
+file, using 3-way merge. This is done by giving
+<tt>git-merge-one-file</tt> command as one of the arguments to
+<tt>git-merge-index</tt> command:</p>
+<div class="listingblock">
+<div class="content">
+<pre><tt>$ 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</tt></pre>
+</div></div>
+<p><tt>git-merge-one-file</tt> 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 <tt>merge</tt> program from RCS suite to perform a
+file-level 3-way merge. In this case, <tt>merge</tt> detects
+conflicts, and the merge result with conflict marks is left in
+the working tree.. This can be seen if you run <tt>ls-files
+--stage</tt> again at this point:</p>
+<div class="listingblock">
+<div class="content">
+<pre><tt>$ git-ls-files --stage
+100644 7f8b141b65fdcee47321e399a2598a235a032422 0 example
+100644 263414f423d0e4d70dae8fe53fa34614ff3e2860 1 hello
+100644 06fa6a24256dc7e560efa5687fa84b51f0263c3a 2 hello
+100644 cc44c73eb783565da5831b4d820c962954019b69 3 hello</tt></pre>
+</div></div>
+<p>This is the state of the index file and the working file after
+<tt>git merge</tt> returns control back to you, leaving the conflicting
+merge for you to resolve. Notice that the path <tt>hello</tt> is still
+unmerged, and what you see with <tt>git diff</tt> at this point is
+differences since stage 2 (i.e. your version).</p>
+</div>
+<h2>Publishing your work</h2>
+<div class="sectionbody">
+<p>So, we can use somebody else's work from a remote repository, but
+how can <strong>you</strong> prepare a repository to let other people pull from
+it?</p>
+<p>You do your real work in your working tree that has your
+primary repository hanging under it as its <tt>.git</tt> subdirectory.
+You <strong>could</strong> 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
+<em>pushing</em>.</p>
+<div class="admonitionblock">
+<table><tr>
+<td class="icon">
+<div class="title">Note</div>
+</td>
+<td class="content">This public repository could further be mirrored, and that is
+how git repositories at <tt>kernel.org</tt> are managed.</td>
+</tr></table>
+</div>
+<p>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, <tt>git-receive-pack</tt>.</p>
+<p>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.</p>
+<div class="admonitionblock">
+<table><tr>
+<td class="icon">
+<div class="title">Note</div>
+</td>
+<td class="content"><tt>git push</tt> uses a pair of programs,
+<tt>git-send-pack</tt> on your local machine, and <tt>git-receive-pack</tt>
+on the remote machine. The communication between the two over
+the network internally uses an SSH connection.</td>
+</tr></table>
+</div>
+<p>Your private repository's git directory is usually <tt>.git</tt>, but
+your public repository is often named after the project name,
+i.e. <tt><project>.git</tt>. Let's create such a public repository for
+project <tt>my-git</tt>. After logging into the remote machine, create
+an empty directory:</p>
+<div class="listingblock">
+<div class="content">
+<pre><tt>$ mkdir my-git.git</tt></pre>
+</div></div>
+<p>Then, make that directory into a git repository by running
+<tt>git init</tt>, but this time, since its name is not the usual
+<tt>.git</tt>, we do things slightly differently:</p>
+<div class="listingblock">
+<div class="content">
+<pre><tt>$ GIT_DIR=my-git.git git-init</tt></pre>
+</div></div>
+<p>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 <tt>git-receive-pack</tt>
+program on the <tt>$PATH</tt>.</p>
+<div class="admonitionblock">
+<table><tr>
+<td class="icon">
+<div class="title">Note</div>
+</td>
+<td class="content">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 <tt>bash</tt>, only <tt>.bashrc</tt> is read and not
+<tt>.bash_profile</tt>. As a workaround, make sure <tt>.bashrc</tt> sets up
+<tt>$PATH</tt> so that you can run <tt>git-receive-pack</tt> program.</td>
+</tr></table>
+</div>
+<div class="admonitionblock">
+<table><tr>
+<td class="icon">
+<div class="title">Note</div>
+</td>
+<td class="content">If you plan to publish this repository to be accessed over http,
+you should do <tt>chmod +x my-git.git/hooks/post-update</tt> at this
+point. This makes sure that every time you push into this
+repository, <tt>git-update-server-info</tt> is run.</td>
+</tr></table>
+</div>
+<p>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:</p>
+<div class="listingblock">
+<div class="content">
+<pre><tt>$ git push <public-host>:/path/to/my-git.git master</tt></pre>
+</div></div>
+<p>This synchronizes your public repository to match the named
+branch head (i.e. <tt>master</tt> in this case) and objects reachable
+from them in your current repository.</p>
+<p>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:</p>
+<div class="listingblock">
+<div class="content">
+<pre><tt>$ git push master.kernel.org:/pub/scm/git/git.git/</tt></pre>
+</div></div>
+</div>
+<h2>Packing your repository</h2>
+<div class="sectionbody">
+<p>Earlier, we saw that one file under <tt>.git/objects/??/</tt> 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</p>
+<div class="listingblock">
+<div class="content">
+<pre><tt>$ git repack</tt></pre>
+</div></div>
+<p>will do it for you. If you followed the tutorial examples, you
+would have accumulated about 17 objects in <tt>.git/objects/??/</tt>
+directories by now. <tt>git repack</tt> tells you how many objects it
+packed, and stores the packed file in <tt>.git/objects/pack</tt>
+directory.</p>
+<div class="admonitionblock">
+<table><tr>
+<td class="icon">
+<div class="title">Note</div>
+</td>
+<td class="content">You will see two files, <tt>pack-*.pack</tt> and <tt>pack-*.idx</tt>,
+in <tt>.git/objects/pack</tt> 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.</td>
+</tr></table>
+</div>
+<p>If you are paranoid, running <tt>git-verify-pack</tt> command would
+detect if you have a corrupt pack, but do not worry too much.
+Our programs are always perfect ;-).</p>
+<p>Once you have packed objects, you do not need to leave the
+unpacked objects that are contained in the pack file anymore.</p>
+<div class="listingblock">
+<div class="content">
+<pre><tt>$ git prune-packed</tt></pre>
+</div></div>
+<p>would remove them for you.</p>
+<p>You can try running <tt>find .git/objects -type f</tt> before and after
+you run <tt>git prune-packed</tt> if you are curious. Also <tt>git
+count-objects</tt> would tell you how many unpacked objects are in
+your repository and how much space they are consuming.</p>
+<div class="admonitionblock">
+<table><tr>
+<td class="icon">
+<div class="title">Note</div>
+</td>
+<td class="content"><tt>git pull</tt> 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.</td>
+</tr></table>
+</div>
+<p>If you run <tt>git repack</tt> again at this point, it will say
+"Nothing to pack". Once you continue your development and
+accumulate the changes, running <tt>git repack</tt> 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 <tt>git repack</tt> every once in a
+while, depending on how active your project is.</p>
+<p>When a repository is synchronized via <tt>git push</tt> and <tt>git pull</tt>
+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.</p>
+</div>
+<h2>Working with Others</h2>
+<div class="sectionbody">
+<p>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
+<a href="http://www.xenotime.net/linux/mentor/linux-mentoring-2006.pdf">Randy Dunlap's presentation</a>.</p>
+<p>It should be stressed that this hierarchy is purely <strong>informal</strong>.
+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.</p>
+<p>A recommended workflow for a "project lead" goes like this:</p>
+<ol>
+<li>
+<p>
+Prepare your primary repository on your local machine. Your
+ work is done there.
+</p>
+</li>
+<li>
+<p>
+Prepare a public repository accessible to others.
+</p>
+<p>If other people are pulling from your repository over dumb
+transport protocols (HTTP), you need to keep this repository
+<em>dumb transport friendly</em>. After <tt>git init</tt>,
+<tt>$GIT_DIR/hooks/post-update</tt> copied from the standard templates
+would contain a call to <tt>git-update-server-info</tt> but the
+<tt>post-update</tt> hook itself is disabled by default — enable it
+with <tt>chmod +x post-update</tt>. This makes sure <tt>git-update-server-info</tt>
+keeps the necessary files up-to-date.</p>
+</li>
+<li>
+<p>
+Push into the public repository from your primary
+ repository.
+</p>
+</li>
+<li>
+<p>
+<tt>git repack</tt> the public repository. This establishes a big
+ pack that contains the initial set of objects as the
+ baseline, and possibly <tt>git prune</tt> if the transport
+ used for pulling from your repository supports packed
+ repositories.
+</p>
+</li>
+<li>
+<p>
+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".
+</p>
+<p>You can repack this private repository whenever you feel like.</p>
+</li>
+<li>
+<p>
+Push your changes to the public repository, and announce it
+ to the public.
+</p>
+</li>
+<li>
+<p>
+Every once in a while, "git repack" the public repository.
+ Go back to step 5. and continue working.
+</p>
+</li>
+</ol>
+<p>A recommended work cycle for a "subsystem maintainer" who works
+on that project and has an own "public repository" goes like this:</p>
+<ol>
+<li>
+<p>
+Prepare your work repository, by <tt>git clone</tt> the public
+ repository of the "project lead". The URL used for the
+ initial cloning is stored in the remote.origin.url
+ configuration variable.
+</p>
+</li>
+<li>
+<p>
+Prepare a public repository accessible to others, just like
+ the "project lead" person does.
+</p>
+</li>
+<li>
+<p>
+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 <tt>objects/info/alternates</tt> file to
+ point at the repository you are borrowing from.
+</p>
+</li>
+<li>
+<p>
+Push into the public repository from your primary
+ repository. Run <tt>git repack</tt>, and possibly <tt>git prune</tt> if the
+ transport used for pulling from your repository supports
+ packed repositories.
+</p>
+</li>
+<li>
+<p>
+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".
+</p>
+<p>You can repack this private repository whenever you feel
+like.</p>
+</li>
+<li>
+<p>
+Push your changes to your public repository, and ask your
+ "project lead" and possibly your "sub-subsystem
+ maintainers" to pull from it.
+</p>
+</li>
+<li>
+<p>
+Every once in a while, <tt>git repack</tt> the public repository.
+ Go back to step 5. and continue working.
+</p>
+</li>
+</ol>
+<p>A recommended work cycle for an "individual developer" who does
+not have a "public" repository is somewhat different. It goes
+like this:</p>
+<ol>
+<li>
+<p>
+Prepare your work repository, by <tt>git clone</tt> 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 the remote.origin.url
+ configuration variable.
+</p>
+</li>
+<li>
+<p>
+Do your work in your repository on <em>master</em> branch.
+</p>
+</li>
+<li>
+<p>
+Run <tt>git fetch origin</tt> from the public repository of your
+ upstream every once in a while. This does only the first
+ half of <tt>git pull</tt> but does not merge. The head of the
+ public repository is stored in <tt>.git/refs/remotes/origin/master</tt>.
+</p>
+</li>
+<li>
+<p>
+Use <tt>git cherry origin</tt> to see which ones of your patches
+ were accepted, and/or use <tt>git rebase origin</tt> to port your
+ unmerged changes forward to the updated upstream.
+</p>
+</li>
+<li>
+<p>
+Use <tt>git format-patch origin</tt> to prepare patches for e-mail
+ submission to your upstream and send it out. Go back to
+ step 2. and continue.
+</p>
+</li>
+</ol>
+</div>
+<h2>Working with Others, Shared Repository Style</h2>
+<div class="sectionbody">
+<p>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.</p>
+<p>See <a href="gitcvs-migration.html">gitcvs-migration(7)</a>[git for CVS users] for the details.</p>
+</div>
+<h2>Bundling your work together</h2>
+<div class="sectionbody">
+<p>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.</p>
+<p>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:</p>
+<div class="listingblock">
+<div class="content">
+<pre><tt>$ 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.</tt></pre>
+</div></div>
+<p>Both fixes are tested well, and at this point, you want to merge
+in both of them. You could merge in <em>diff-fix</em> first and then
+<em>commit-fix</em> next, like this:</p>
+<div class="listingblock">
+<div class="content">
+<pre><tt>$ git merge -m "Merge fix in diff-fix" diff-fix
+$ git merge -m "Merge fix in commit-fix" commit-fix</tt></pre>
+</div></div>
+<p>Which would result in:</p>
+<div class="listingblock">
+<div class="content">
+<pre><tt>$ 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.</tt></pre>
+</div></div>
+<p>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 <em>master~2</em>:</p>
+<div class="listingblock">
+<div class="content">
+<pre><tt>$ git reset --hard master~2</tt></pre>
+</div></div>
+<p>You can make sure <em>git show-branch</em> matches the state before
+those two <em>git merge</em> you just did. Then, instead of running
+two <em>git merge</em> commands in a row, you would merge these two
+branch heads (this is known as <em>making an Octopus</em>):</p>
+<div class="listingblock">
+<div class="content">
+<pre><tt>$ git merge 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.</tt></pre>
+</div></div>
+<p>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 merging 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.</p>
+</div>
+<h2>SEE ALSO</h2>
+<div class="sectionbody">
+<p><a href="gittutorial.html">gittutorial(7)</a>, <a href="gittutorial-2.html">gittutorial-2(7)</a>,
+<a href="giteveryday.html">giteveryday(7)</a>, <a href="gitcvs-migration.html">gitcvs-migration(7)</a>,
+<a href="user-manual.html">The Git User's Manual</a></p>
+</div>
+<h2>GIT</h2>
+<div class="sectionbody">
+<p>Part of the <a href="git.html">git(7)</a> suite.</p>
+</div>
+<div id="footer">
+<div id="footer-text">
+Last updated 02-Jun-2008 07:30:07 UTC
+</div>
+</div>
+</body>
+</html>
|