Merge branch 'master' of git://linux-nfs.org/~bfields/git

This is in the hope of giving JBF's user-manual wider exposure.
I am not very happy with trailing whitespaces in the new
document, but let's not worry too much about the formatting
issues for now, but concentrate more on the structure and the
contents.

4 files changed, 3273 insertions, 1 deletions

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 5314068d32..5e012f48e3 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -17,7 +17,7 @@ ARTICLES += hooks
 ARTICLES += everyday
 ARTICLES += git-tools
 # with their own formatting rules.
-SP_ARTICLES = glossary howto/revert-branch-rebase
+SP_ARTICLES = glossary howto/revert-branch-rebase user-manual
 
 DOC_HTML += $(patsubst %,%.html,$(ARTICLES) $(SP_ARTICLES))
 
@@ -99,6 +99,12 @@ clean:
 %.xml : %.txt
 	asciidoc -b docbook -d manpage -f asciidoc.conf $<
 
+user-manual.xml: user-manual.txt user-manual.conf
+	asciidoc -b docbook -d book $<
+
+user-manual.html: user-manual.xml
+	xmlto -m /etc/asciidoc/docbook-xsl/xhtml.xsl html-nochunks $<
+
 glossary.html : glossary.txt sort_glossary.pl
 	cat $< | \
 	perl sort_glossary.pl | \
diff --git a/Documentation/docbook-xsl.css b/Documentation/docbook-xsl.css
new file mode 100644
index 0000000000..8821e305dd
--- /dev/null
+++ b/Documentation/docbook-xsl.css
@@ -0,0 +1,286 @@
+/*

+  CSS stylesheet for XHTML produced by DocBook XSL stylesheets.

+  Tested with XSL stylesheets 1.61.2, 1.67.2

+*/

+

+span.strong {

+  font-weight: bold;

+}

+

+body blockquote {

+  margin-top: .75em;

+  line-height: 1.5;

+  margin-bottom: .75em;

+}

+

+html body {

+  margin: 1em 5% 1em 5%;

+  line-height: 1.2;

+}

+

+body div {

+  margin: 0;

+}

+

+h1, h2, h3, h4, h5, h6,

+div.toc p b,

+div.list-of-figures p b,

+div.list-of-tables p b,

+div.abstract p.title

+{

+  color: #527bbd;

+  font-family: tahoma, verdana, sans-serif;

+}

+

+div.toc p:first-child,

+div.list-of-figures p:first-child,

+div.list-of-tables p:first-child,

+div.example p.title

+{

+  margin-bottom: 0.2em;

+}

+

+body h1 {

+  margin: .0em 0 0 -4%;

+  line-height: 1.3;

+  border-bottom: 2px solid silver;

+}

+

+body h2 {

+  margin: 0.5em 0 0 -4%;

+  line-height: 1.3;

+  border-bottom: 2px solid silver;

+}

+

+body h3 {

+  margin: .8em 0 0 -3%;

+  line-height: 1.3;

+}

+

+body h4 {

+  margin: .8em 0 0 -3%;

+  line-height: 1.3;

+}

+

+body h5 {

+  margin: .8em 0 0 -2%;

+  line-height: 1.3;

+}

+

+body h6 {

+  margin: .8em 0 0 -1%;

+  line-height: 1.3;

+}

+

+body hr {

+  border: none; /* Broken on IE6 */

+}

+div.footnotes hr {

+  border: 1px solid silver;

+}

+

+div.navheader th, div.navheader td, div.navfooter td {

+  font-family: sans-serif;

+  font-size: 0.9em;

+  font-weight: bold;

+  color: #527bbd;

+}

+div.navheader img, div.navfooter img {

+  border-style: none;

+}

+div.navheader a, div.navfooter a {

+  font-weight: normal;

+}

+div.navfooter hr {

+  border: 1px solid silver;

+}

+

+body td {

+  line-height: 1.2

+}

+

+body th {

+  line-height: 1.2;

+}

+

+ol {

+  line-height: 1.2;

+}

+

+ul, body dir, body menu {

+  line-height: 1.2;

+}

+

+html {

+  margin: 0; 

+  padding: 0;

+}

+

+body h1, body h2, body h3, body h4, body h5, body h6 {

+  margin-left: 0

+} 

+

+body pre {

+  margin: 0.5em 10% 0.5em 1em;

+  line-height: 1.0;

+  color: navy;

+}

+

+tt.literal, code.literal {

+  color: navy;

+}

+

+div.literallayout p {

+  padding: 0em;

+  margin: 0em;

+}

+

+div.literallayout {

+  font-family: monospace;

+#  margin: 0.5em 10% 0.5em 1em;

+  margin: 0em;

+  color: navy;

+  border: 1px solid silver;

+  background: #f4f4f4;

+  padding: 0.5em;

+}

+

+.programlisting, .screen {

+  border: 1px solid silver;

+  background: #f4f4f4;

+  margin: 0.5em 10% 0.5em 0;

+  padding: 0.5em 1em;

+}

+

+div.sidebar {

+  background: #ffffee;

+  margin: 1.0em 10% 0.5em 0;

+  padding: 0.5em 1em;

+  border: 1px solid silver;

+}

+div.sidebar * { padding: 0; }

+div.sidebar div { margin: 0; }

+div.sidebar p.title {

+  font-family: sans-serif;

+  margin-top: 0.5em;

+  margin-bottom: 0.2em;

+}

+

+div.bibliomixed {

+  margin: 0.5em 5% 0.5em 1em;

+}

+

+div.glossary dt {

+  font-weight: bold;

+}

+div.glossary dd p {

+  margin-top: 0.2em;

+}

+

+dl {

+  margin: .8em 0;

+  line-height: 1.2;

+}

+

+dt {

+  margin-top: 0.5em;

+}

+

+dt span.term {

+  font-style: italic;

+}

+

+div.variablelist dd p {

+  margin-top: 0;

+}

+

+div.itemizedlist li, div.orderedlist li {

+  margin-left: -0.8em;

+  margin-top: 0.5em;

+}

+

+ul, ol {

+    list-style-position: outside;

+}

+

+div.sidebar ul, div.sidebar ol {

+    margin-left: 2.8em;

+}

+

+div.itemizedlist p.title,

+div.orderedlist p.title,

+div.variablelist p.title

+{

+  margin-bottom: -0.8em;

+}

+

+div.revhistory table {

+  border-collapse: collapse;

+  border: none;

+}

+div.revhistory th {

+  border: none;

+  color: #527bbd;

+  font-family: tahoma, verdana, sans-serif;

+}

+div.revhistory td {

+  border: 1px solid silver;

+}

+

+/* Keep TOC and index lines close together. */

+div.toc dl, div.toc dt,

+div.list-of-figures dl, div.list-of-figures dt,

+div.list-of-tables dl, div.list-of-tables dt,

+div.indexdiv dl, div.indexdiv dt

+{

+  line-height: normal;

+  margin-top: 0;

+  margin-bottom: 0;

+}

+

+/*

+  Table styling does not work because of overriding attributes in

+  generated HTML.

+*/

+div.table table,

+div.informaltable table

+{

+    margin-left: 0;

+    margin-right: 5%;

+    margin-bottom: 0.8em;

+}

+div.informaltable table

+{

+    margin-top: 0.4em

+}

+div.table thead,

+div.table tfoot,

+div.table tbody,

+div.informaltable thead,

+div.informaltable tfoot,

+div.informaltable tbody

+{

+    /* No effect in IE6. */

+    border-top: 2px solid #527bbd;

+    border-bottom: 2px solid #527bbd;

+}

+div.table thead, div.table tfoot,

+div.informaltable thead, div.informaltable tfoot

+{

+    font-weight: bold;

+}

+

+div.mediaobject img {

+    border: 1px solid silver;

+    margin-bottom: 0.8em;

+}

+div.figure p.title,

+div.table p.title

+{

+  margin-top: 1em;

+  margin-bottom: 0.4em;

+}

+

+@media print {

+  div.navheader, div.navfooter { display: none; }

+}

diff --git a/Documentation/user-manual.conf b/Documentation/user-manual.conf
new file mode 100644
index 0000000000..92b01ecf71
--- /dev/null
+++ b/Documentation/user-manual.conf
@@ -0,0 +1,21 @@
+[titles]
+	underlines="__","==","--","~~","^^"
+
+[attributes]
+caret=^
+startsb=&#91;
+endsb=&#93;
+tilde=&#126;
+
+[gitlink-inlinemacro]
+<ulink url="{target}.html">{target}{0?({0})}</ulink>
+
+ifdef::backend-docbook[]
+# "unbreak" docbook-xsl v1.68 for manpages. v1.69 works with or without this.
+[listingblock]
+<example><title>{title}</title>
+<literallayout>
+|
+</literallayout>
+{title#}</example>
+endif::backend-docbook[]
diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
new file mode 100644
index 0000000000..b6916d11b2
--- /dev/null
+++ b/Documentation/user-manual.txt
@@ -0,0 +1,2959 @@
+Git User's Manual
+_________________
+
+This manual is designed to be readable by someone with basic unix
+commandline skills, but no previous knowledge of git.
+
+Chapter 1 gives a brief overview of git commands, without any
+explanation; you may prefer to skip to chapter 2 on a first reading.
+
+Chapters 2 and 3 explain how to fetch and study a project using
+git--the tools you'd need to build and test a particular version of a
+software project, to search for regressions, and so on.
+
+Chapter 4 explains how to do development with git, and chapter 5 how
+to share that development with others.
+
+Further chapters cover more specialized topics.
+
+Comprehensive reference documentation is available through the man
+pages.  For a command such as "git clone", just use
+
+------------------------------------------------
+$ man git-clone
+------------------------------------------------
+
+Git Quick Start
+===============
+
+This is a quick summary of the major commands; the following chapters
+will explain how these work in more detail.
+
+Creating a new repository
+-------------------------
+
+From a tarball:
+
+-----------------------------------------------
+$ tar xzf project.tar.gz
+$ cd project
+$ git init
+Initialized empty Git repository in .git/
+$ git add .
+$ git commit
+-----------------------------------------------
+
+From a remote repository:
+
+-----------------------------------------------
+$ git clone git://example.com/pub/project.git
+$ cd project
+-----------------------------------------------
+
+Managing branches
+-----------------
+
+-----------------------------------------------
+$ git branch	     # list all branches in this repo
+$ git checkout test  # switch working directory to branch "test"
+$ git branch new     # create branch "new" starting at current HEAD
+$ git branch -d new  # delete branch "new"
+-----------------------------------------------
+
+Instead of basing new branch on current HEAD (the default), use:
+
+-----------------------------------------------
+$ git branch new test    # branch named "test"
+$ git branch new v2.6.15 # tag named v2.6.15
+$ git branch new HEAD^   # commit before the most recent
+$ git branch new HEAD^^  # commit before that
+$ git branch new test~10 # ten commits before tip of branch "test"
+-----------------------------------------------
+
+Create and switch to a new branch at the same time:
+
+-----------------------------------------------
+$ git checkout -b new v2.6.15
+-----------------------------------------------
+
+Update and examine branches from the repository you cloned from:
+
+-----------------------------------------------
+$ git fetch		# update
+$ git branch -r		# list
+  origin/master
+  origin/next
+  ...
+$ git branch checkout -b masterwork origin/master
+-----------------------------------------------
+
+Fetch a branch from a different repository, and give it a new
+name in your repository:
+
+-----------------------------------------------
+$ git fetch git://example.com/project.git theirbranch:mybranch
+$ git fetch git://example.com/project.git v2.6.15:mybranch
+-----------------------------------------------
+
+Keep a list of repositories you work with regularly:
+
+-----------------------------------------------
+$ git remote add example git://example.com/project.git
+$ git remote			# list remote repositories
+example
+origin
+$ git remote show example	# get details
+* remote example
+  URL: git://example.com/project.git
+  Tracked remote branches
+    master next ...
+$ git fetch example		# update branches from example
+$ git branch -r			# list all remote branches
+-----------------------------------------------
+
+
+Exploring history
+-----------------
+
+-----------------------------------------------
+$ gitk			    # visualize and browse history
+$ git log		    # list all commits
+$ git log src/		    # ...modifying src/
+$ git log v2.6.15..v2.6.16  # ...in v2.6.16, not in v2.6.15
+$ git log master..test	    # ...in branch test, not in branch master
+$ git log test..master	    # ...in branch master, but not in test
+$ git log test...master	    # ...in one branch, not in both
+$ git log -S'foo()'	    # ...where difference contain "foo()"
+$ git log --since="2 weeks ago"
+$ git log -p		    # show patches as well
+$ git show		    # most recent commit
+$ git diff v2.6.15..v2.6.16 # diff between two tagged versions
+$ git diff v2.6.15..HEAD    # diff with current head
+$ git grep "foo()"	    # search working directory for "foo()"
+$ git grep v2.6.15 "foo()"  # search old tree for "foo()"
+$ git show v2.6.15:a.txt    # look at old version of a.txt
+-----------------------------------------------
+
+Search for regressions:
+
+-----------------------------------------------
+$ git bisect start
+$ git bisect bad		# current version is bad
+$ git bisect good v2.6.13-rc2	# last known good revision
+Bisecting: 675 revisions left to test after this
+				# test here, then:
+$ git bisect good		# if this revision is good, or
+$ git bisect bad		# if this revision is bad.
+				# repeat until done.
+-----------------------------------------------
+
+Making changes
+--------------
+
+Make sure git knows who to blame:
+
+------------------------------------------------
+$ cat >~/.gitconfig <<\EOF
+[user]
+name = Your Name Comes Here
+email = you@yourdomain.example.com
+EOF
+------------------------------------------------
+
+Select file contents to include in the next commit, then make the
+commit:
+
+-----------------------------------------------
+$ git add a.txt    # updated file
+$ git add b.txt    # new file
+$ git rm c.txt     # old file
+$ git commit
+-----------------------------------------------
+
+Or, prepare and create the commit in one step:
+
+-----------------------------------------------
+$ git commit d.txt # use latest content only of d.txt
+$ git commit -a	   # use latest content of all tracked files
+-----------------------------------------------
+
+Merging
+-------
+
+-----------------------------------------------
+$ git merge test   # merge branch "test" into the current branch
+$ git pull git://example.com/project.git master
+		   # fetch and merge in remote branch
+$ git pull . test  # equivalent to git merge test
+-----------------------------------------------
+
+Sharing your changes
+--------------------
+
+Importing or exporting patches:
+
+-----------------------------------------------
+$ git format-patch origin..HEAD # format a patch for each commit
+				# in HEAD but not in origin
+$ git-am mbox # import patches from the mailbox "mbox"
+-----------------------------------------------
+
+Fetch a branch in a different git repository, then merge into the
+current branch:
+
+-----------------------------------------------
+$ git pull git://example.com/project.git theirbranch
+-----------------------------------------------
+
+Store the fetched branch into a local branch before merging into the
+current branch:
+
+-----------------------------------------------
+$ git pull git://example.com/project.git theirbranch:mybranch
+-----------------------------------------------
+
+After creating commits on a local branch, update the remote
+branch with your commits:
+
+-----------------------------------------------
+$ git push ssh://example.com/project.git mybranch:theirbranch
+-----------------------------------------------
+
+When remote and local branch are both named "test":
+
+-----------------------------------------------
+$ git push ssh://example.com/project.git test
+-----------------------------------------------
+
+Shortcut version for a frequently used remote repository:
+
+-----------------------------------------------
+$ git remote add example ssh://example.com/project.git
+$ git push example test
+-----------------------------------------------
+
+Repository maintenance
+----------------------
+
+Check for corruption:
+
+-----------------------------------------------
+$ git fsck
+-----------------------------------------------
+
+Recompress, remove unused cruft:
+
+-----------------------------------------------
+$ git gc
+-----------------------------------------------
+
+Repositories and Branches
+=========================
+
+How to get a git repository
+---------------------------
+
+It will be useful to have a git repository to experiment with as you
+read this manual.
+
+The best way to get one is by using the gitlink:git-clone[1] command
+to download a copy of an existing repository for a project that you
+are interested in.  If you don't already have a project in mind, here
+are some interesting examples:
+
+------------------------------------------------
+	# git itself (approx. 10MB download):
+$ git clone git://git.kernel.org/pub/scm/git/git.git
+	# the linux kernel (approx. 150MB download):
+$ git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git
+------------------------------------------------
+
+The initial clone may be time-consuming for a large project, but you
+will only need to clone once.
+
+The clone command creates a new directory named after the project
+("git" or "linux-2.6" in the examples above).  After you cd into this
+directory, you will see that it contains a copy of the project files,
+together with a special top-level directory named ".git", which
+contains all the information about the history of the project.
+
+In most of the following, examples will be taken from one of the two
+repositories above.
+
+How to check out a different version of a project
+-------------------------------------------------
+
+Git is best thought of as a tool for storing the history of a
+collection of files.  It stores the history as a compressed
+collection of interrelated snapshots (versions) of the project's
+contents.
+
+A single git repository may contain multiple branches.  Each branch
+is a bookmark referencing a particular point in the project history.
+The gitlink:git-branch[1] command shows you the list of branches:
+
+------------------------------------------------
+$ git branch
+* master
+------------------------------------------------
+
+A freshly cloned repository contains a single branch, named "master",
+and the working directory contains the version of the project
+referred to by the master branch.
+
+Most projects also use tags.  Tags, like branches, are references
+into the project's history, and can be listed using the
+gitlink:git-tag[1] command:
+
+------------------------------------------------
+$ git tag -l
+v2.6.11
+v2.6.11-tree
+v2.6.12
+v2.6.12-rc2
+v2.6.12-rc3
+v2.6.12-rc4
+v2.6.12-rc5
+v2.6.12-rc6
+v2.6.13
+...
+------------------------------------------------
+
+Tags are expected to always point at the same version of a project,
+while branches are expected to advance as development progresses.
+
+Create a new branch pointing to one of these versions and check it
+out using gitlink:git-checkout[1]:
+
+------------------------------------------------
+$ git checkout -b new v2.6.13
+------------------------------------------------
+
+The working directory then reflects the contents that the project had
+when it was tagged v2.6.13, and gitlink:git-branch[1] shows two
+branches, with an asterisk marking the currently checked-out branch:
+
+------------------------------------------------
+$ git branch
+  master
+* new
+------------------------------------------------
+
+If you decide that you'd rather see version 2.6.17, you can modify
+the current branch to point at v2.6.17 instead, with
+
+------------------------------------------------
+$ git reset --hard v2.6.17
+------------------------------------------------
+
+Note that if the current branch was your only reference to a
+particular point in history, then resetting that branch may leave you
+with no way to find the history it used to point to; so use this
+command carefully.
+
+Understanding History: Commits
+------------------------------
+
+Every change in the history of a project is represented by a commit.
+The gitlink:git-show[1] command shows the most recent commit on the
+current branch:
+
+------------------------------------------------
+$ git show
+commit 2b5f6dcce5bf94b9b119e9ed8d537098ec61c3d2
+Author: Jamal Hadi Salim <hadi@cyberus.ca>
+Date:   Sat Dec 2 22:22:25 2006 -0800
+
+    [XFRM]: Fix aevent structuring to be more complete.
+    
+    aevents can not uniquely identify an SA. We break the ABI with this
+    patch, but consensus is that since it is not yet utilized by any
+    (known) application then it is fine (better do it now than later).
+    
+    Signed-off-by: Jamal Hadi Salim <hadi@cyberus.ca>
+    Signed-off-by: David S. Miller <davem@davemloft.net>
+
+diff --git a/Documentation/networking/xfrm_sync.txt b/Documentation/networking/xfrm_sync.txt
+index 8be626f..d7aac9d 100644
+--- a/Documentation/networking/xfrm_sync.txt
++++ b/Documentation/networking/xfrm_sync.txt
+@@ -47,10 +47,13 @@ aevent_id structure looks like:
+ 
+    struct xfrm_aevent_id {
+              struct xfrm_usersa_id           sa_id;
++             xfrm_address_t                  saddr;
+              __u32                           flags;
++             __u32                           reqid;
+    };
+...
+------------------------------------------------
+
+As you can see, a commit shows who made the latest change, what they
+did, and why.
+
+Every commit has a 40-hexdigit id, sometimes called the "object name"
+or the "SHA1 id", shown on the first line of the "git show" output.
+You can usually refer to a commit by a shorter name, such as a tag or a
+branch name, but this longer name can also be useful.  Most
+importantly, it is a globally unique name for this commit: so if you
+tell somebody else the object name (for example in email), then you are
+guaranteed that name will refer to the same commit in their repository
+that you it does in yours (assuming their repository has that commit at
+all).
+
+Understanding history: commits, parents, and reachability
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Every commit (except the very first commit in a project) also has a
+parent commit which shows what happened before this commit.
+Following the chain of parents will eventually take you back to the
+beginning of the project.
+
+However, the commits do not form a simple list; git allows lines of
+development to diverge and then reconverge, and the point where two
+lines of development reconverge is called a "merge".  The commit
+representing a merge can therefore have more than one parent, with
+each parent representing the most recent commit on one of the lines
+of development leading to that point.
+
+The best way to see how this works is using the gitlink:gitk[1]
+command; running gitk now on a git repository and looking for merge
+commits will help understand how the git organizes history.
+
+In the following, we say that commit X is "reachable" from commit Y
+if commit X is an ancestor of commit Y.  Equivalently, you could say
+that Y is a descendent of X, or that there is a chain of parents
+leading from commit Y to commit X.
+
+Undestanding history: History diagrams
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+We will sometimes represent git history using diagrams like the one
+below.  Commits are shown as "o", and the links between them with
+lines drawn with - / and \.  Time goes left to right:
+
+         o--o--o <-- Branch A
+        /
+ o--o--o <-- master
+        \
+         o--o--o <-- Branch B
+
+If we need to talk about a particular commit, the character "o" may
+be replaced with another letter or number.
+
+Understanding history: What is a branch?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Though we've been using the word "branch" to mean a kind of reference
+to a particular commit, the word branch is also commonly used to
+refer to the line of commits leading up to that point.  In the
+example above, git may think of the branch named "A" as just a
+pointer to one particular commit, but we may refer informally to the
+line of three commits leading up to that point as all being part of
+"branch A".
+
+If we need to make it clear that we're just talking about the most
+recent commit on the branch, we may refer to that commit as the
+"head" of the branch.
+
+Manipulating branches
+---------------------
+
+Creating, deleting, and modifying branches is quick and easy; here's
+a summary of the commands:
+
+git branch::
+	list all branches
+git branch <branch>::
+	create a new branch named <branch>, referencing the same
+	point in history as the current branch
+git branch <branch> <start-point>::
+	create a new branch named <branch>, referencing
+	<start-point>, which may be specified any way you like,
+	including using a branch name or a tag name
+git branch -d <branch>::
+	delete the branch <branch>; if the branch you are deleting
+	points to a commit which is not reachable from this branch,
+	this command will fail with a warning.
+git branch -D <branch>::
+	even if the branch points to a commit not reachable
+	from the current branch, you may know that that commit
+	is still reachable from some other branch or tag.  In that
+	case it is safe to use this command to force git to delete
+	the branch.
+git checkout <branch>::
+	make the current branch <branch>, updating the working
+	directory to reflect the version referenced by <branch>
+git checkout -b <new> <start-point>::
+	create a new branch <new> referencing <start-point>, and
+	check it out.
+
+It is also useful to know that the special symbol "HEAD" can always
+be used to refer to the current branch.
+
+Examining branches from a remote repository
+-------------------------------------------
+
+The "master" branch that was created at the time you cloned is a copy
+of the HEAD in the repository that you cloned from.  That repository
+may also have had other branches, though, and your local repository
+keeps branches which track each of those remote branches, which you
+can view using the "-r" option to gitlink:git-branch[1]:
+
+------------------------------------------------
+$ git branch -r
+  origin/HEAD
+  origin/html
+  origin/maint
+  origin/man
+  origin/master
+  origin/next
+  origin/pu
+  origin/todo
+------------------------------------------------
+
+You cannot check out these remote-tracking branches, but you can
+examine them on a branch of your own, just as you would a tag:
+
+------------------------------------------------
+$ git checkout -b my-todo-copy origin/todo
+------------------------------------------------
+
+Note that the name "origin" is just the name that git uses by default
+to refer to the repository that you cloned from.
+
+[[how-git-stores-references]]
+Naming branches, tags, and other references
+-------------------------------------------
+
+Branches, remote-tracking branches, and tags are all references to
+commits.  All references are named with a slash-separated path name
+starting with "refs"; the names we've been using so far are actually
+shorthand:
+
+	- The branch "test" is short for "refs/heads/test".
+	- The tag "v2.6.18" is short for "refs/tags/v2.6.18".
+	- "origin/master" is short for "refs/remotes/origin/master".
+
+The full name is occasionally useful if, for example, there ever
+exists a tag and a branch with the same name.
+
+As another useful shortcut, if the repository "origin" posesses only
+a single branch, you can refer to that branch as just "origin".
+
+More generally, if you have defined a remote repository named
+"example", you can refer to the branch in that repository as
+"example".  And for a repository with multiple branches, this will
+refer to the branch designated as the "HEAD" branch.
+
+For the complete list of paths which git checks for references, and
+the order it uses to decide which to choose when there are multiple
+references with the same shorthand name, see the "SPECIFYING
+REVISIONS" section of gitlink:git-rev-parse[1].
+
+[[Updating-a-repository-with-git-fetch]]
+Updating a repository with git fetch
+------------------------------------
+
+Eventually the developer cloned from will do additional work in her
+repository, creating new commits and advancing the branches to point
+at the new commits.
+
+The command "git fetch", with no arguments, will update all of the
+remote-tracking branches to the latest version found in her
+repository.  It will not touch any of your own branches--not even the
+"master" branch that was created for you on clone.
+
+Fetching branches from other repositories
+-----------------------------------------
+
+You can also track branches from repositories other than the one you
+cloned from, using gitlink:git-remote[1]:
+
+-------------------------------------------------
+$ git remote add linux-nfs git://linux-nfs.org/pub/nfs-2.6.git
+$ git fetch
+* refs/remotes/linux-nfs/master: storing branch 'master' ...
+  commit: bf81b46
+-------------------------------------------------
+
+New remote-tracking branches will be stored under the shorthand name
+that you gave "git remote add", in this case linux-nfs:
+
+-------------------------------------------------
+$ git branch -r
+linux-nfs/master
+origin/master
+-------------------------------------------------
+
+If you run "git fetch <remote>" later, the tracking branches for the
+named <remote> will be updated.
+
+If you examine the file .git/config, you will see that git has added
+a new stanza:
+
+-------------------------------------------------
+$ cat .git/config
+...
+[remote "linux-nfs"]
+        url = git://linux-nfs.org/~bfields/git.git
+	fetch = +refs/heads/*:refs/remotes/linux-nfs-read/*
+...
+-------------------------------------------------
+
+This is what causes git to track the remote's branches; you may modify
+or delete these configuration options by editing .git/config with a
+text editor.  (See the "CONFIGURATION FILE" section of
+gitlink:git-config[1] for details.)
+
+Exploring git history
+=====================
+
+Git is best thought of as a tool for storing the history of a
+collection of files.  It does this by storing compressed snapshots of
+the contents of a file heirarchy, together with "commits" which show
+the relationships between these snapshots.
+
+Git provides extremely flexible and fast tools for exploring the
+history of a project.
+
+We start with one specialized tool which is useful for finding the
+commit that introduced a bug into a project.
+
+How to use bisect to find a regression
+--------------------------------------
+
+Suppose version 2.6.18 of your project worked, but the version at
+"master" crashes.  Sometimes the best way to find the cause of such a
+regression is to perform a brute-force search through the project's
+history to find the particular commit that caused the problem.  The
+gitlink:git-bisect[1] command can help you do this:
+
+-------------------------------------------------
+$ git bisect start
+$ git bisect good v2.6.18
+$ git bisect bad master
+Bisecting: 3537 revisions left to test after this
+[65934a9a028b88e83e2b0f8b36618fe503349f8e] BLOCK: Make USB storage depend on SCSI rather than selecting it [try #6]
+-------------------------------------------------
+
+If you run "git branch" at this point, you'll see that git has
+temporarily moved you to a new branch named "bisect".  This branch
+points to a commit (with commit id 65934...) that is reachable from
+v2.6.19 but not from v2.6.18.  Compile and test it, and see whether
+it crashes.  Assume it does crash.  Then:
+
+-------------------------------------------------
+$ git bisect bad
+Bisecting: 1769 revisions left to test after this
+[7eff82c8b1511017ae605f0c99ac275a7e21b867] i2c-core: Drop useless bitmaskings
+-------------------------------------------------
+
+checks out an older version.  Continue like this, telling git at each
+stage whether the version it gives you is good or bad, and notice
+that the number of revisions left to test is cut approximately in
+half each time.
+
+After about 13 tests (in this case), it will output the commit id of
+the guilty commit.  You can then examine the commit with
+gitlink:git-show[1], find out who wrote it, and mail them your bug
+report with the commit id.  Finally, run
+
+-------------------------------------------------
+$ git bisect reset
+-------------------------------------------------
+
+to return you to the branch you were on before and delete the
+temporary "bisect" branch.
+
+Note that the version which git-bisect checks out for you at each
+point is just a suggestion, and you're free to try a different
+version if you think it would be a good idea.  For example,
+occasionally you may land on a commit that broke something unrelated;
+run
+
+-------------------------------------------------
+$ git bisect-visualize
+-------------------------------------------------
+
+which will run gitk and label the commit it chose with a marker that
+says "bisect".  Chose a safe-looking commit nearby, note its commit
+id, and check it out with:
+
+-------------------------------------------------
+$ git reset --hard fb47ddb2db...
+-------------------------------------------------
+
+then test, run "bisect good" or "bisect bad" as appropriate, and
+continue.
+
+Naming commits
+--------------
+
+We have seen several ways of naming commits already:
+
+	- 40-hexdigit object name
+	- branch name: refers to the commit at the head of the given
+	  branch
+	- tag name: refers to the commit pointed to by the given tag
+	  (we've seen branches and tags are special cases of
+	  <<how-git-stores-references,references>>).
+	- HEAD: refers to the head of the current branch
+
+There are many more; see the "SPECIFYING REVISIONS" section of the
+gitlink:git-rev-parse[1] man page for the complete list of ways to
+name revisions.  Some examples:
+
+-------------------------------------------------
+$ git show fb47ddb2 # the first few characters of the object name
+		    # are usually enough to specify it uniquely
+$ git show HEAD^    # the parent of the HEAD commit
+$ git show HEAD^^   # the grandparent
+$ git show HEAD~4   # the great-great-grandparent
+-------------------------------------------------