Instead of writing the results out to `$GIT_INDEX_FILE`,
	write the resulting index in the named file.  While the
	command is operating, the original index file is locked
	with the same mechanism as usual.  The file must allow
	to be rename(2)ed into from a temporary file that is
	created next to the usual index file; typically this
	means it needs to be on the same filesystem as the index
	file itself, and you need write permission to the
	directories the index file and index output file are
	located in.

--[no-]recurse-submodules::
	Using --recurse-submodules will update the content of all active
	submodules according to the commit recorded in the superproject by
	calling read-tree recursively, also setting the submodules' HEAD to be
	detached at that commit.

--no-sparse-checkout::
	Disable sparse checkout support even if `core.sparseCheckout`
	is true.

--empty::
	Instead of reading tree object(s) into the index, just empty
	it.

-q::
--quiet::
	Quiet, suppress feedback messages.

<tree-ish#>::
	The id of the tree object(s) to be read/merged.


MERGING
-------
If `-m` is specified, 'git read-tree' can perform 3 kinds of
merge, a single tree merge if only 1 tree is given, a
fast-forward merge with 2 trees, or a 3-way merge if 3 or more trees are
provided.


Single Tree Merge
~~~~~~~~~~~~~~~~~
If only 1 tree is specified, 'git read-tree' operates as if the user did not
specify `-m`, except that if the original index has an entry for a
given pathname, and the contents of the path match with the tree
being read, the stat info from the index is used. (In other words, the
index's stat()s take precedence over the merged tree's).

That means that if you do a `git read-tree -m <newtree>` followed by a
`git checkout-index -f -u -a`, the 'git checkout-index' only checks out
the stuff that really changed.

This is used to avoid unnecessary false hits when 'git diff-files' is
run after 'git read-tree'.


Two Tree Merge
~~~~~~~~~~~~~~

Typically, this is invoked as `git read-tree -m $H $M`, where $H
is the head commit of the current repository, and $M is the head
of a foreign tree, which is simply ahead of $H (i.e. we are in a
fast-forward situation).

When two trees are specified, the user is telling 'git read-tree'
the following:

     1. The current index and work tree is derived from $H, but
	the user may have local changes in them since $H.

     2. The user wants to fast-forward to $M.

In this case, the `git read-tree -m $H $M` command makes sure
that no local change is lost as the result of this "merge".
Here are the "carry forward" rules, where "I" denotes the index,
"clean" means that index and work tree coincide, and "exists"/"nothing"
refer to the presence of a path in the specified commit:

....
	I                   H        M        Result
       -------------------------------------------------------
     0  nothing             nothing  nothing  (does not happen)
     1  nothing             nothing  exists   use M
     2  nothing             exists   nothing  remove path from index
     3  nothing             exists   exists,  use M if "initial checkout",
				     H == M   keep index otherwise
				     exists,  fail
				     H != M

        clean I==H  I==M
       ------------------
     4  yes   N/A   N/A     nothing  nothing  keep index
     5  no    N/A   N/A     nothing  nothing  keep index

     6  yes   N/A   yes     nothing  exists   keep index
     7  no    N/A   yes     nothing  exists   keep index
     8  yes   N/A   no      nothing  exists   fail
     9  no    N/A   no      nothing  exists   fail

     10 yes   yes   N/A     exists   nothing  remove path from index
     11 no    yes   N/A     exists   nothing  fail
     12 yes   no    N/A     exists   nothing  fail
     13 no    no    N/A     exists   nothing  fail

	clean (H==M)
       ------
     14 yes                 exists   exists   keep index
     15 no                  exists   exists   keep index

        clean I==H  I==M (H!=M)
       ------------------