summaryrefslogtreecommitdiff
path: root/Documentation
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/Makefile8
-rw-r--r--Documentation/docbook-xsl.css286
-rw-r--r--Documentation/user-manual.conf21
-rw-r--r--Documentation/user-manual.txt2959
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
+-------------------------------------------------
+
+Recall that merge commits may have more than one parent; by default,
+^ and ~ follow the first parent listed in the commit, but you can
+also choose:
+
+-------------------------------------------------
+$ git show HEAD^1 # show the first parent of HEAD
+$ git show HEAD^2 # show the second parent of HEAD
+-------------------------------------------------
+
+In addition to HEAD, there are several other special names for
+commits:
+
+Merges (to be discussed later), as well as operations such as
+git-reset, which change the currently checked-out commit, generally
+set ORIG_HEAD to the value HEAD had before the current operation.
+
+The git-fetch operation always stores the head of the last fetched
+branch in FETCH_HEAD. For example, if you run git fetch without
+specifying a local branch as the target of the operation
+
+-------------------------------------------------
+$ git fetch git://example.com/proj.git theirbranch
+-------------------------------------------------
+
+the fetched commits will still be available from FETCH_HEAD.
+
+When we discuss merges we'll also see the special name MERGE_HEAD,
+which refers to the ot