git-read-tree(1)
================
-v0.1, May 2005
NAME
----
-git-read-tree - Reads tree information into the directory cache
+git-read-tree - Reads tree information into the index
SYNOPSIS
--------
-'git-read-tree' (<tree-ish> | [-m [-u]] <tree-ish1> [<tree-ish2> [<tree-ish3>]])
+'git-read-tree' (<tree-ish> | [-m [-u|-i]] <tree-ish1> [<tree-ish2> [<tree-ish3>]])
DESCRIPTION
-----------
-Reads the tree information given by <tree-ish> into the directory cache,
+Reads the tree information given by <tree-ish> into the index,
but does not actually *update* any of the files it "caches". (see:
git-checkout-index)
-Optionally, it can merge a tree into the cache, perform a
+Optionally, it can merge a tree into the index, perform a
fast-forward (i.e. 2-way) merge, or a 3-way merge, with the -m
flag. When used with -m, the -u flag causes it to also update
the files in the work tree with the result of the merge.
-m::
Perform a merge, not just a read.
+--reset::
+
+ Same as -m except that unmerged entries will be silently ignored.
+
-u::
After a successful merge, update the files in the work
tree with the result of the merge.
+-i::
+ Usually a merge requires the index file as well as the
+ files in the working tree are up to date with the
+ current head commit, in order not to lose local
+ changes. This flag disables the check with the working
+ tree and is meant to be used when creating a merge of
+ trees that are not directly related to the current
+ working tree status into a temporary index file.
+
+
<tree-ish#>::
The id of the tree object(s) to be read/merged.
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 cache has an entry for a
+specify '-m', except that if the original index has an entry for a
given pathname, and the contents of the path matches with the tree
-being read, the stat info from the cache is used. (In other words, the
-cache's stat()s take precedence over the merged tree's).
+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
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
+ 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.
+ 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".
-------------------------------------------------------
0 nothing nothing nothing (does not happen)
1 nothing nothing exists use M
- 2 nothing exists nothing remove path from cache
+ 2 nothing exists nothing remove path from index
3 nothing exists exists use M
clean I==H I==M
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 cache
+ 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
20 yes yes no exists exists use M
21 no yes no exists exists fail
-In all "keep index" cases, the cache entry stays as in the
+In all "keep index" cases, the index entry stays as in the
original index file. If the entry were not up to date,
git-read-tree keeps the copy in the work tree intact when
operating under the -u flag.
changes. To illustrate, suppose you start from what has been
commited last to your repository:
- $ JC=`cat .git/HEAD`
+ $ 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
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 cache entries since $JC, and if you haven't,
+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