Merge branch 'maint'

* maint:
  git-apply: fix whitespace stripping
  apply --index-info: fall back to current index for mode changes
  core-tutorial: minor cleanup
  documentation: replace Discussion section by link to user-manual chapter
  user-manual: todo updates and cleanup
  user-manual: fix introduction to packfiles
  user-manual: move packfile and dangling object discussion
  user-manual: rewrite object database discussion
  user-manual: reorder commit, blob, tree discussion
  user-manual: rewrite index discussion
  user-manual: create new "low-level git operations" chapter
  user-manual: rename "git internals" to "git concepts"
  user-manual: move object format details to hacking-git chapter
  user-manual: adjust section levels in "git internals"
  revision walker: --cherry-pick is a limited operation
  git-sh-setup: typofix in comments

Documentation/Makefile

@@ -123,7 +123,7 @@ cmd-list.made: cmd-list.perl $(MAN1_TXT)
 	perl ./cmd-list.perl
 	date >$@
 
-git.7 git.html: git.txt core-intro.txt
+git.7 git.html: git.txt
 
 clean:
 	$(RM) *.xml *.xml+ *.html *.html+ *.1 *.5 *.7 *.texi *.texi+ howto-index.txt howto/*.html doc.dep

Documentation/core-tutorial.txt

@@ -4,34 +4,24 @@ A git core tutorial for developers
 Introduction
 ------------
 
-This is trying to be a short tutorial on setting up and using a git
-repository, mainly because being hands-on and using explicit examples is
-often the best way of explaining what is going on.
+This tutorial explains how to use the "core" git programs to set up and
+work with a git repository.
 
-In normal life, most people wouldn't use the "core" git programs
-directly, but rather script around them to make them more palatable.
-Understanding the core git stuff may help some people get those scripts
-done, though, and it may also be instructive in helping people
-understand what it is that the higher-level helper scripts are actually
-doing.
+If you just need to use git as a revision control system you may prefer
+to start with link:tutorial.html[a tutorial introduction to git] or
+link:user-manual.html[the git user manual].
+
+However, an understanding of these low-level tools can be helpful if
+you want to understand git's internals.
 
 The core git is often called "plumbing", with the prettier user
 interfaces on top of it called "porcelain". You may not want to use the
 plumbing directly very often, but it can be good to know what the
 plumbing does for when the porcelain isn't flushing.
 
-The material presented here often goes deep describing how things
-work internally.  If you are mostly interested in using git as a
-SCM, you can skip them during your first pass.
-
 [NOTE]
-And those "too deep" descriptions are often marked as Note.
-
-[NOTE]
-If you are already familiar with another version control system,
-like CVS, you may want to take a look at
-link:everyday.html[Everyday GIT in 20 commands or so] first
-before reading this.
+Deeper technical details are often marked as Notes, which you can
+skip on your first reading.
 
 
 Creating a git repository
@@ -1686,5 +1676,3 @@ merge two at a time, documenting how you resolved the conflicts,
 and the reason why you preferred changes made in one side over
 the other.  Otherwise it would make the project history harder
 to follow, not easier.
-
-[ to be continued.. cvsimports ]

Documentation/git.txt

@@ -134,9 +134,9 @@ FURTHER DOCUMENTATION
 See the references above to get started using git.  The following is
 probably more detail than necessary for a first-time user.
 
-The <<Discussion,Discussion>> section below and the
-link:core-tutorial.html[Core tutorial] both provide introductions to the
-underlying git architecture.
+The link:user-manual.html#git-concepts[git concepts chapter of the
+user-manual] and the link:core-tutorial.html[Core tutorial] both provide
+introductions to the underlying git architecture.
 
 See also the link:howto-index.html[howto] documents for some useful
 examples.
@@ -474,7 +474,56 @@ for further details.
 
 Discussion[[Discussion]]
 ------------------------
-include::core-intro.txt[]
+
+More detail on the following is available from the
+link:user-manual.html#git-concepts[git concepts chapter of the
+user-manual] and the link:core-tutorial.html[Core tutorial].
+
+A git project normally consists of a working directory with a ".git"
+subdirectory at the top level.  The .git directory contains, among other
+things, a compressed object database representing the complete history
+of the project, an "index" file which links that history to the current
+contents of the working tree, and named pointers into that history such
+as tags and branch heads.
+
+The object database contains objects of three main types: blobs, which
+hold file data; trees, which point to blobs and other trees to build up
+directory heirarchies; and commits, which each reference a single tree
+and some number of parent commits.
+
+The commit, equivalent to what other systems call a "changeset" or
+"version", represents a step in the project's history, and each parent
+represents an immediately preceding step.  Commits with more than one
+parent represent merges of independent lines of development.
+
+All objects are named by the SHA1 hash of their contents, normally
+written as a string of 40 hex digits.  Such names are globally unique.
+The entire history leading up to a commit can be vouched for by signing
+just that commit.  A fourth object type, the tag, is provided for this
+purpose.
+
+When first created, objects are stored in individual files, but for
+efficiency may later be compressed together into "pack files".
+
+Named pointers called refs mark interesting points in history.  A ref
+may contain the SHA1 name of an object or the name of another ref.  Refs
+with names beginning `ref/head/` contain the SHA1 name of the most
+recent commit (or "head") of a branch under developement.  SHA1 names of
+tags of interest are stored under `ref/tags/`.  A special ref named
+`HEAD` contains the name of the currently checked-out branch.
+
+The index file is initialized with a list of all paths and, for each
+path, a blob object and a set of attributes.  The blob object represents
+the contents of the file as of the head of the current branch.  The
+attributes (last modified time, size, etc.) are taken from the
+corresponding file in the working tree.  Subsequent changes to the
+working tree can be found by comparing these attributes.  The index may
+be updated with new content, and new commits may be created from the
+content stored in the index.
+
+The index is also capable of storing multiple entries (called "stages")
+for a given pathname.  These stages are used to hold the various
+unmerged version of a file when a merge is in progress.
 
 Authors
 -------