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