Merge branch 'lt/tree' into jc/lt-tree-n-cache-tree

* lt/tree: (98 commits)
  Remove "tree->entries" tree-entry list from tree parser
  Switch "read_tree_recursive()" over to tree-walk functionality
  Make "tree_entry" have a SHA1 instead of a union of object pointers
  Add raw tree buffer info to "struct tree"
  Don't use "sscanf()" for tree mode scanning
  git-fetch: avoid using "case ... in (arm)"
  mailinfo: skip bogus UNIX From line inside body
  mailinfo: More carefully parse header lines in read_one_header_line()
  Allow in body headers beyond the in body header prefix.
  More accurately detect header lines in read_one_header_line
  In handle_body only read a line if we don't already have one.
  Refactor commit messge handling.
  Move B and Q decoding into check header.
  Make read_one_header_line return a flag not a length.
  Fix memory leak in "git rev-list --objects"
  gitview: Move the console error messages to message dialog
  gitview: Add key binding for F5.
  Let git-clone to pass --template=dir option to git-init-db.
  Make cvsexportcommit create parent directories as needed.
  Document current cvsexportcommit limitations.
  ...

Conflicts:

	Makefile, builtin.h, git.c are trivially resolved.
	builtin-read-tree.c needed adjustment for the tree
	parser change.

73 files changed, 2532 insertions, 1033 deletions

diff --git a/.gitignore b/.gitignore
index 7906909b30..afd0876218 100644
--- a/.gitignore
+++ b/.gitignore
@@ -77,6 +77,7 @@ git-prune
 git-prune-packed
 git-pull
 git-push
+git-quiltimport
 git-read-tree
 git-rebase
 git-receive-pack
@@ -115,6 +116,7 @@ git-update-index
 git-update-ref
 git-update-server-info
 git-upload-pack
+git-upload-tar
 git-var
 git-verify-pack
 git-verify-tag
diff --git a/Documentation/Makefile b/Documentation/Makefile
index c1af22ce04..2b0efe7921 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -7,6 +7,7 @@ MAN7_TXT=git.txt
 DOC_HTML=$(patsubst %.txt,%.html,$(MAN1_TXT) $(MAN7_TXT))
 
 ARTICLES = tutorial
+ARTICLES += tutorial-2
 ARTICLES += core-tutorial
 ARTICLES += cvs-migration
 ARTICLES += diffcore
@@ -51,9 +52,9 @@ man1: $(DOC_MAN1)
 man7: $(DOC_MAN7)
 
 install: man
-	$(INSTALL) -d -m755 $(DESTDIR)/$(man1) $(DESTDIR)/$(man7)
-	$(INSTALL) $(DOC_MAN1) $(DESTDIR)/$(man1)
-	$(INSTALL) $(DOC_MAN7) $(DESTDIR)/$(man7)
+	$(INSTALL) -d -m755 $(DESTDIR)$(man1) $(DESTDIR)$(man7)
+	$(INSTALL) $(DOC_MAN1) $(DESTDIR)$(man1)
+	$(INSTALL) $(DOC_MAN7) $(DESTDIR)$(man7)
 
 
 #
diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt
index 5e3112943d..6342ea33e4 100644
--- a/Documentation/git-add.txt
+++ b/Documentation/git-add.txt
@@ -14,11 +14,13 @@ DESCRIPTION
 A simple wrapper for git-update-index to add files to the index,
 for people used to do "cvs add".
 
+It only adds non-ignored files, to add ignored files use
+"git update-index --add".
 
 OPTIONS
 -------
 <file>...::
-	Files to add to the index.
+	Files to add to the index (see gitlink:git-ls-files[1]).
 
 -n::
         Don't actually add the file(s), just show if they exist.
@@ -68,6 +70,7 @@ git-add git-*.sh::
 See Also
 --------
 gitlink:git-rm[1]
+gitlink:git-ls-files[1]
 
 Author
 ------
diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt
index 72fb2f89b4..0b37e2bfc8 100644
--- a/Documentation/git-branch.txt
+++ b/Documentation/git-branch.txt
@@ -43,6 +43,9 @@ OPTIONS
 
 <branchname>::
 	The name of the branch to create or delete.
+	The new branch name must pass all checks defined by
+	gitlink:git-check-ref-format[1].  Some of these checks
+	may restrict the characters allowed in a branch name.
 
 <start-point>::
 	The new branch will be created with a HEAD equal to this.  It may
diff --git a/Documentation/git-cat-file.txt b/Documentation/git-cat-file.txt
index 504eb1b16a..5e9cbf875d 100644
--- a/Documentation/git-cat-file.txt
+++ b/Documentation/git-cat-file.txt
@@ -8,12 +8,12 @@ git-cat-file - Provide content or type information for repository objects
 
 SYNOPSIS
 --------
-'git-cat-file' [-t | -s | -e | <type>] <object>
+'git-cat-file' [-t | -s | -e | -p | <type>] <object>
 
 DESCRIPTION
 -----------
 Provides content or type of objects in the repository. The type
-is required unless '-t' is used to find the object type,
+is required unless '-t' or '-p' is used to find the object type,
 or '-s' is used to find the object size.
 
 OPTIONS
@@ -33,6 +33,9 @@ OPTIONS
 	Suppress all output; instead exit with zero status if <object>
 	exists and is a valid object.
 
+-p::
+	Pretty-print the contents of <object> based on its type.
+
 <type>::
 	Typically this matches the real type of <object> but asking
 	for a type that can trivially be dereferenced from the given
@@ -49,6 +52,8 @@ If '-s' is specified, the size of the <object> in bytes.
 
 If '-e' is specified, no output.
 
+If '-p' is specified, the contents of <object> are pretty-printed.
+
 Otherwise the raw (though uncompressed) contents of the <object> will
 be returned.
 
diff --git a/Documentation/git-check-ref-format.txt b/Documentation/git-check-ref-format.txt
index 7dc1bdb6ef..3ea720dd00 100644
--- a/Documentation/git-check-ref-format.txt
+++ b/Documentation/git-check-ref-format.txt
@@ -45,6 +45,8 @@ refname expressions (see gitlink:git-rev-parse[1]).  Namely:
 
 . colon `:` is used as in `srcref:dstref` to mean "use srcref\'s
   value and store it in dstref" in fetch and push operations.
+  It may also be used to select a specific object such as with
+  gitlink:git-cat-file[1] "git-cat-file blob v1.3.3:refs.c".
 
 
 GIT
diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index 095128906a..d82efc00d4 100644
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt
@@ -35,7 +35,10 @@ OPTIONS
 	Force a re-read of everything.
 
 -b::
-	Create a new branch and start it at <branch>.
+	Create a new branch named <new_branch> and start it at
+	<branch>.  The new branch name must pass all checks defined
+	by gitlink:git-check-ref-format[1].  Some of these checks
+	may restrict the characters allowed in a branch name.
 
 -m::
 	If you have local modifications to one or more files that
diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt
index b333f51045..94d9393372 100644
--- a/Documentation/git-clone.txt
+++ b/Documentation/git-clone.txt
@@ -9,8 +9,8 @@ git-clone - Clones a repository
 SYNOPSIS
 --------
 [verse]
-'git-clone' [-l [-s]] [-q] [-n] [--bare] [-o <name>] [-u <upload-pack>]
-	  [--reference <repository>]
+'git-clone' [--template=<template_directory>] [-l [-s]] [-q] [-n] [--bare]
+	  [-o <name>] [-u <upload-pack>] [--reference <repository>]
 	  <repository> [<directory>]
 
 DESCRIPTION
@@ -89,6 +89,11 @@ OPTIONS
 	the command to specify non-default path for the command
 	run on the other end.
 
+--template=<template_directory>::
+	Specify the directory from which templates will be used;
+	if unset the templates are taken from the installation
+	defined default, typically `/usr/share/git-core/templates`.
+
 <repository>::
 	The (possibly remote) repository to clone from.  It can
 	be any URL git-fetch supports.
diff --git a/Documentation/tutorial-2.txt b/Documentation/tutorial-2.txt
new file mode 100644
index 0000000000..08d3453e5c
--- /dev/null
+++ b/Documentation/tutorial-2.txt
@@ -0,0 +1,391 @@
+A tutorial introduction to git: part two
+========================================
+
+You should work through link:tutorial.html[A tutorial introduction to
+git] before reading this tutorial.
+
+The goal of this tutorial is to introduce two fundamental pieces of
+git's architecture--the object database and the index file--and to
+provide the reader with everything necessary to understand the rest
+of the git documentation.
+
+The git object database
+-----------------------
+
+Let's start a new project and create a small amount of history:
+
+------------------------------------------------
+$ mkdir test-project
+$ cd test-project
+$ git init-db
+defaulting to local storage area
+$ echo 'hello world' > file.txt
+$ git add .
+$ git commit -a -m "initial commit"
+Committing initial tree 92b8b694ffb1675e5975148e1121810081dbdffe
+$ echo 'hello world!' >file.txt
+$ git commit -a -m "add emphasis"
+------------------------------------------------
+
+What are the 40 digits of hex that git responded to the first commit
+with?
+
+We saw in part one of the tutorial that commits have names like this.
+It turns out that every object in the git history is stored under
+such a 40-digit hex name.  That name is the SHA1 hash of the object's
+contents; among other things, this ensures that git will never store
+the same data twice (since identical data is given an identical SHA1
+name), and that the contents of a git object will never change (since
+that would change the object's name as well).
+
+We can ask git about this particular object with the cat-file
+command--just cut-and-paste from the reply to the initial commit, to
+save yourself typing all 40 hex digits:
+
+------------------------------------------------
+$ git cat-file -t 92b8b694ffb1675e5975148e1121810081dbdffe
+tree
+------------------------------------------------
+
+A tree can refer to one or more "blob" objects, each corresponding to
+a file.  In addition, a tree can also refer to other tree objects,
+thus creating a directory heirarchy.  You can examine the contents of
+any tree using ls-tree (remember that a long enough initial portion
+of the SHA1 will also work):
+
+------------------------------------------------
+$ git ls-tree 92b8b694
+100644 blob 3b18e512dba79e4c8300dd08aeb37f8e728b8dad    file.txt
+------------------------------------------------
+
+Thus we see that this tree has one file in it.  The SHA1 hash is a
+reference to that file's data:
+
+------------------------------------------------
+$ git cat-file -t 3b18e512
+blob
+------------------------------------------------
+
+A "blob" is just file data, which we can also examine with cat-file:
+
+------------------------------------------------
+$ git cat-file blob 3b18e512
+hello world
+------------------------------------------------
+
+Note that this is the old file data; so the object that git named in
+its response to the initial tree was a tree with a snapshot of the
+directory state that was recorded by the first commit.
+
+All of these objects are stored under their SHA1 names inside the git
+directory:
+
+------------------------------------------------
+$ find .git/objects/
+.git/objects/
+.git/objects/pack
+.git/objects/info
+.git/objects/3b
+.git/objects/3b/18e512dba79e4c8300dd08aeb37f8e728b8dad
+.git/objects/92
+.git/objects/92/b8b694ffb1675e5975148e1121810081dbdffe
+.git/objects/54
+.git/objects/54/196cc2703dc165cbd373a65a4dcf22d50ae7f7
+.git/objects/a0
+.git/objects/a0/423896973644771497bdc03eb99d5281615b51
+.git/objects/d0
+.git/objects/d0/492b368b66bdabf2ac1fd8c92b39d3db916e59
+.git/objects/c4
+.git/objects/c4/d59f390b9cfd4318117afde11d601c1085f241
+------------------------------------------------
+
+and the contents of these files is just the compressed data plus a
+header identifying their length and their type.  The type is either a
+blob, a tree, a commit, or a tag.  We've seen a blob and a tree now,
+so next we should look at a commit.
+
+The simplest commit to find is the HEAD commit, which we can find
+from .git/HEAD:
+
+------------------------------------------------
+$ cat .git/HEAD
+ref: refs/heads/master
+------------------------------------------------
+
+As you can see, this tells us which branch we're currently on, and it
+tells us this by naming a file under the .git directory, which itself
+contains a SHA1 name referring to a commit object, which we can
+examine with cat-file:
+
+------------------------------------------------
+$ cat .git/refs/heads/master
+c4d59f390b9cfd4318117afde11d601c1085f241
+$ git cat-file -t c4d59f39
+commit
+$ git cat-file commit c4d59f39
+tree d0492b368b66bdabf2ac1fd8c92b39d3db916e59
+parent 54196cc2703dc165cbd373a65a4dcf22d50ae7f7
+author J. Bruce Fields <bfields@puzzle.fieldses.org> 1143418702 -0500
+committer J. Bruce Fields <bfields@puzzle.fieldses.org> 1143418702 -0500
+
+add emphasis
+------------------------------------------------
+
+The "tree" object here refers to the new state of the tree:
+
+------------------------------------------------
+$ git ls-tree d0492b36
+100644 blob a0423896973644771497bdc03eb99d5281615b51    file.txt
+$ git cat-file commit a0423896
+hello world!
+------------------------------------------------
+
+and the "parent" object refers to the previous commit:
+
+------------------------------------------------
+$ git-cat-file commit 54196cc2
+tree 92b8b694ffb1675e5975148e1121810081dbdffe
+author J. Bruce Fields <bfields@puzzle.fieldses.org> 1143414668 -0500
+committer J. Bruce Fields <bfields@puzzle.fieldses.org> 1143414668 -0500
+
+initial commit
+------------------------------------------------
+
+The tree object is the tree we examined first, and this commit is
+unusual in that it lacks any parent.
+
+Most commits have only one parent, but it is also common for a commit
+to have multiple parents.   In that case the commit represents a
+merge, with the parent references pointing to the heads of the merged
+branches.
+
+Besides blobs, trees, and commits, the only remaining type of object
+is a "tag", which we won't discuss here; refer to gitlink:git-tag[1]
+for details.
+
+So now we know how git uses the object database to represent a
+project's history:
+
+  * "commit" objects refer to "tree" objects representing the
+    snapshot of a directory tree at a particular point in the
+    history, and refer to "parent" commits to show how they're
+    connected into the project history.
+  * "tree" objects represent the state of a single directory,
+    associating directory names to "blob" objects containing file
+    data and "tree" objects containing subdirectory information.
+  * "blob" objects contain file data without any other structure.
+  * References to commit objects at the head of each branch are
+    stored in files under .git/refs/heads/.
+  * The name of the current branch is stored in .git/HEAD.
+
+Note, by the way, that lots of commands take a tree as an argument.
+But as we can see above, a tree can be referred to in many different
+ways--by the SHA1 name for that tree, by the name of a commit that
+refers to the tree, by the name of a branch whose head refers to that
+tree, etc.--and most such commands can accept any of these names.
+
+In command synopses, the word "tree-ish" is sometimes used to
+designate such an argument.
+
+The index file
+--------------
+
+The primary tool we've been using to create commits is "git commit
+-a", which creates a commit including every change you've made to
+your working tree.  But what if you want to commit changes only to
+certain files?  Or only certain changes to certain files?
+
+If we look at the way commits are created under the cover, we'll see
+that there are more flexible ways creating commits.
+
+Continuing with our test-project, let's modify file.txt again:
+
+------------------------------------------------
+$ echo "hello world, again" >>file.txt
+------------------------------------------------
+
+but this time instead of immediately making the commit, let's take an
+intermediate step, and ask for diffs along the way to keep track of
+what's happening:
+
+------------------------------------------------
+$ git diff
+--- a/file.txt
++++ b/file.txt
+@@ -1 +1,2 @@
+ hello world!
++hello world, again
+$ git update-index file.txt
+$ git diff
+------------------------------------------------
+
+The last diff is empty, but no new commits have been made, and the
+head still doesn't contain the new line:
+
+------------------------------------------------
+$ git-diff HEAD
+diff --git a/file.txt b/file.txt
+index a042389..513feba 100644
+--- a/file.txt
++++ b/file.txt
+@@ -1 +1,2 @@
+ hello world!
++hello world, again
+------------------------------------------------
+
+So "git diff" is comparing against something other than the head.
+The thing that it's comparing against is actually the index file,
+which is stored in .git/index in a binary format, but whose contents
+we can examine with ls-files:
+
+------------------------------------------------
+$ git ls-files --stage
+100644 513feba2e53ebbd2532419ded848ba19de88ba00 0       file.txt
+$ git cat-file -t 513feba2
+blob
+$ git cat-file blob 513feba2
+hello world, again
+------------------------------------------------
+
+So what our "git update-index" did was store a new blob and then put
+a reference to it in the index file.  If we modify the file again,
+we'll see that the new modifications are reflected in the "git-diff"
+output:
+
+------------------------------------------------
+$ echo 'again?' >>file.txt
+$ git diff
+index 513feba..ba3da7b 100644
+--- a/file.txt
++++ b/file.txt
+@@ -1,2 +1,3 @@
+ hello world!
+ hello world, again
++again?
+------------------------------------------------
+
+With the right arguments, git diff can also show us the difference
+between the working directory and the last commit, or between the
+index and the last commit:
+
+------------------------------------------------
+$ git diff HEAD
+diff --git a/file.txt b/file.txt
+index a042389..ba3da7b 100644
+--- a/file.txt
++++ b/file.txt
+@@ -1 +1,3 @@
+ hello world!
++hello world, again
++again?
+$ git diff --cached
+diff --git a/file.txt b/file.txt
+index a042389..513feba 10