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