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