1git-read-tree(1) 2================ 3 4NAME 5---- 6git-read-tree - Reads tree information into the index 7 8 9SYNOPSIS 10-------- 11'git-read-tree' (<tree-ish> | [[-m | --reset] [-u | -i]] <tree-ish1> [<tree-ish2> [<tree-ish3>]]) 12 13 14DESCRIPTION 15----------- 16Reads the tree information given by <tree-ish> into the index, 17but does not actually *update* any of the files it "caches". (see: 18gitlink:git-checkout-index[1]) 19 20Optionally, it can merge a tree into the index, perform a 21fast-forward (i.e. 2-way) merge, or a 3-way merge, with the `-m` 22flag. When used with `-m`, the `-u` flag causes it to also update 23the files in the work tree with the result of the merge. 24 25Trivial merges are done by `git-read-tree` itself. Only conflicting paths 26will be in unmerged state when `git-read-tree` returns. 27 28OPTIONS 29------- 30-m:: 31 Perform a merge, not just a read. The command will 32 refuse to run if your index file has unmerged entries, 33 indicating that you have not finished previous merge you 34 started. 35 36--reset:: 37 Same as -m, except that unmerged entries are discarded 38 instead of failing. 39 40-u:: 41 After a successful merge, update the files in the work 42 tree with the result of the merge. 43 44-i:: 45 Usually a merge requires the index file as well as the 46 files in the working tree are up to date with the 47 current head commit, in order not to lose local 48 changes. This flag disables the check with the working 49 tree and is meant to be used when creating a merge of 50 trees that are not directly related to the current 51 working tree status into a temporary index file. 52 53<tree-ish#>:: 54 The id of the tree object(s) to be read/merged. 55 56 57Merging 58------- 59If `-m` is specified, `git-read-tree` can perform 3 kinds of 60merge, a single tree merge if only 1 tree is given, a 61fast-forward merge with 2 trees, or a 3-way merge if 3 trees are 62provided. 63 64 65Single Tree Merge 66~~~~~~~~~~~~~~~~~ 67If only 1 tree is specified, git-read-tree operates as if the user did not 68specify `-m`, except that if the original index has an entry for a 69given pathname, and the contents of the path matches with the tree 70being read, the stat info from the index is used. (In other words, the 71index's stat()s take precedence over the merged tree's). 72 73That means that if you do a `git-read-tree -m <newtree>` followed by a 74`git-checkout-index -f -u -a`, the `git-checkout-index` only checks out 75the stuff that really changed. 76 77This is used to avoid unnecessary false hits when `git-diff-files` is 78run after `git-read-tree`. 79 80 81Two Tree Merge 82~~~~~~~~~~~~~~ 83 84Typically, this is invoked as `git-read-tree -m $H $M`, where $H 85is the head commit of the current repository, and $M is the head 86of a foreign tree, which is simply ahead of $H (i.e. we are in a 87fast forward situation). 88 89When two trees are specified, the user is telling git-read-tree 90the following: 91 92 1. The current index and work tree is derived from $H, but 93 the user may have local changes in them since $H; 94 95 2. The user wants to fast-forward to $M. 96 97In this case, the `git-read-tree -m $H $M` command makes sure 98that no local change is lost as the result of this "merge". 99Here are the "carry forward" rules: 100 101 I (index) H M Result 102 ------------------------------------------------------- 103 0 nothing nothing nothing (does not happen) 104 1 nothing nothing exists use M 105 2 nothing exists nothing remove path from index 106 3 nothing exists exists use M 107 108 clean I==H I==M 109 ------------------ 110 4 yes N/A N/A nothing nothing keep index 111 5 no N/A N/A nothing nothing keep index 112 113 6 yes N/A yes nothing exists keep index 114 7 no N/A yes nothing exists keep index 115 8 yes N/A no nothing exists fail 116 9 no N/A no nothing exists fail 117 118 10 yes yes N/A exists nothing remove path from index 119 11 no yes N/A exists nothing fail 120 12 yes no N/A exists nothing fail 121 13 no no N/A exists nothing fail 122 123 clean (H=M) 124 ------ 125 14 yes exists exists keep index 126 15 no exists exists keep index 127 128 clean I==H I==M (H!=M) 129 ------------------ 130 16 yes no no exists exists fail 131 17 no no no exists exists fail 132 18 yes no yes exists exists keep index 133 19 no no yes exists exists keep index 134 20 yes yes no exists exists use M 135 21 no yes no exists exists fail 136 137In all "keep index" cases, the index entry stays as in the 138original index file. If the entry were not up to date, 139git-read-tree keeps the copy in the work tree intact when 140operating under the -u flag. 141 142When this form of git-read-tree returns successfully, you can 143see what "local changes" you made are carried forward by running 144`git-diff-index --cached $M`. Note that this does not 145necessarily match `git-diff-index --cached $H` would have 146produced before such a two tree merge. This is because of cases 14718 and 19 --- if you already had the changes in $M (e.g. maybe 148you picked it up via e-mail in a patch form), `git-diff-index 149--cached $H` would have told you about the change before this 150merge, but it would not show in `git-diff-index --cached $M` 151output after two-tree merge. 152 153 1543-Way Merge 155~~~~~~~~~~~ 156Each "index" entry has two bits worth of "stage" state. stage 0 is the 157normal one, and is the only one you'd see in any kind of normal use. 158 159However, when you do `git-read-tree` with three trees, the "stage" 160starts out at 1. 161 162This means that you can do 163 164---------------- 165$ git-read-tree -m <tree1> <tree2> <tree3> 166---------------- 167 168and you will end up with an index with all of the <tree1> entries in 169"stage1", all of the <tree2> entries in "stage2" and all of the 170<tree3> entries in "stage3". When performing a merge of another 171branch into the current branch, we use the common ancestor tree 172as <tree1>, the current branch head as <tree2>, and the other 173branch head as <tree3>. 174 175Furthermore, `git-read-tree` has special-case logic that says: if you see 176a file that matches in all respects in the following states, it 177"collapses" back to "stage0": 178 179 - stage 2 and 3 are the same; take one or the other (it makes no 180 difference - the same work has been done on our branch in 181 stage 2 and their branch in stage 3) 182 183 - stage 1 and stage 2 are the same and stage 3 is different; take 184 stage 3 (our branch in stage 2 did not do anything since the 185 ancestor in stage 1 while their branch in stage 3 worked on 186 it) 187 188 - stage 1 and stage 3 are the same and stage 2 is different take 189 stage 2 (we did something while they did nothing) 190 191The `git-write-tree` command refuses to write a nonsensical tree, and it 192will complain about unmerged entries if it sees a single entry that is not 193stage 0. 194 195Ok, this all sounds like a collection of totally nonsensical rules, 196but it's actually exactly what you want in order to do a fast 197merge. The different stages represent the "result tree" (stage 0, aka 198"merged"), the original tree (stage 1, aka "orig"), and the two trees 199you are trying to merge (stage 2 and 3 respectively). 200 201The order of stages 1, 2 and 3 (hence the order of three 202<tree-ish> command line arguments) are significant when you 203start a 3-way merge with an index file that is already 204populated. Here is an outline of how the algorithm works: 205 206- if a file exists in identical format in all three trees, it will 207 automatically collapse to "merged" state by git-read-tree. 208 209- a file that has _any_ difference what-so-ever in the three trees 210 will stay as separate entries in the index. It's up to "porcelain 211 policy" to determine how to remove the non-0 stages, and insert a 212 merged version. 213 214- the index file saves and restores with all this information, so you 215 can merge things incrementally, but as long as it has entries in 216 stages 1/2/3 (ie "unmerged entries") you can't write the result. So 217 now the merge algorithm ends up being really simple: 218 219 * you walk the index in order, and ignore all entries of stage 0, 220 since they've already been done. 221 222 * if you find a "stage1", but no matching "stage2" or "stage3", you 223 know it's been removed from both trees (it only existed in the 224 original tree), and you remove that entry. 225 226 * if you find a matching "stage2" and "stage3" tree, you remove one 227 of them, and turn the other into a "stage0" entry. Remove any 228 matching "stage1" entry if it exists too. .. all the normal 229 trivial rules .. 230 231You would normally use `git-merge-index` with supplied 232`git-merge-one-file` to do this last step. The script updates 233the files in the working tree as it merges each path and at the 234end of a successful merge. 235 236When you start a 3-way merge with an index file that is already 237populated, it is assumed that it represents the state of the 238files in your work tree, and you can even have files with 239changes unrecorded in the index file. It is further assumed 240that this state is "derived" from the stage 2 tree. The 3-way 241merge refuses to run if it finds an entry in the original index 242file that does not match stage 2. 243 244This is done to prevent you from losing your work-in-progress 245changes, and mixing your random changes in an unrelated merge 246commit. To illustrate, suppose you start from what has been 247commited last to your repository: 248 249---------------- 250$ JC=`git-rev-parse --verify "HEAD^0"` 251$ git-checkout-index -f -u -a $JC 252---------------- 253 254You do random edits, without running git-update-index. And then 255you notice that the tip of your "upstream" tree has advanced 256since you pulled from him: 257 258---------------- 259$ git-fetch git://.... linus 260$ LT=`cat .git/FETCH_HEAD` 261---------------- 262 263Your work tree is still based on your HEAD ($JC), but you have 264some edits since. Three-way merge makes sure that you have not 265added or modified index entries since $JC, and if you haven't, 266then does the right thing. So with the following sequence: 267 268---------------- 269$ git-read-tree -m -u `git-merge-base $JC $LT` $JC $LT 270$ git-merge-index git-merge-one-file -a 271$ echo "Merge with Linus" | \ 272 git-commit-tree `git-write-tree` -p $JC -p $LT 273---------------- 274 275what you would commit is a pure merge between $JC and $LT without 276your work-in-progress changes, and your work tree would be 277updated to the result of the merge. 278 279However, if you have local changes in the working tree that 280would be overwritten by this merge,`git-read-tree` will refuse 281to run to prevent your changes from being lost. 282 283In other words, there is no need to worry about what exists only 284in the working tree. When you have local changes in a part of 285the project that is not involved in the merge, your changes do 286not interfere with the merge, and are kept intact. When they 287*do* interfere, the merge does not even start (`git-read-tree` 288complains loudly and fails without modifying anything). In such 289a case, you can simply continue doing what you were in the 290middle of doing, and when your working tree is ready (i.e. you 291have finished your work-in-progress), attempt the merge again. 292 293 294See Also 295-------- 296gitlink:git-write-tree[1]; gitlink:git-ls-files[1] 297 298 299Author 300------ 301Written by Linus Torvalds <torvalds@osdl.org> 302 303Documentation 304-------------- 305Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. 306 307GIT 308--- 309Part of the gitlink:git[7] suite 310