merges each path and at the
end of a successful merge.

When you start a 3-way merge with an index file that is already
populated, it is assumed that it represents the state of the
files in your work tree, and you can even have files with
changes unrecorded in the index file.  It is further assumed
that this state is "derived" from the stage 2 tree.  The 3-way
merge refuses to run if it finds an entry in the original index
file that does not match stage 2.

This is done to prevent you from losing your work-in-progress
changes, and mixing your random changes in an unrelated merge
commit.  To illustrate, suppose you start from what has been
committed last to your repository:

----------------
$ JC=`git rev-parse --verify "HEAD^0"`
$ git checkout-index -f -u -a $JC
----------------

You do random edits, without running 'git update-index'.  And then
you notice that the tip of your "upstream" tree has advanced
since you pulled from him:

----------------
$ git fetch git://.... linus
$ LT=`git rev-parse FETCH_HEAD`
----------------

Your work tree is still based on your HEAD ($JC), but you have
some edits since.  Three-way merge makes sure that you have not
added or modified index entries since $JC, and if you haven't,
then does the right thing.  So with the following sequence:

----------------
$ git read-tree -m -u `git merge-base $JC $LT` $JC $LT
$ git merge-index git-merge-one-file -a
$ echo "Merge with Linus" | \
  git commit-tree `git write-tree` -p $JC -p $LT
----------------

what you would commit is a pure merge between $JC and $LT without
your work-in-progress changes, and your work tree would be
updated to the result of the merge.

However, if you have local changes in the working tree that
would be overwritten by this merge, 'git read-tree' will refuse
to run to prevent your changes from being lost.

In other words, there is no need to worry about what exists only
in the working tree.  When you have local changes in a part of
the project that is not involved in the merge, your changes do
not interfere with the merge, and are kept intact.  When they
*do* interfere, the merge does not even start ('git read-tree'
complains loudly and fails without modifying anything).  In such
a case, you can simply continue doing what you were in the
middle of doing, and when your working tree is ready (i.e. you
have finished your work-in-progress), attempt the merge again.


SPARSE CHECKOUT
---------------

Note: The skip-worktree capabilities