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 [-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: 18git-checkout-index) 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 git-read-tree -m <tree1> <tree2> <tree3> 165 166and you will end up with an index with all of the <tree1> entries in 167"stage1", all of the <tree2> entries in "stage2" and all of the 168<tree3> entries in "stage3". 169 170Furthermore, "git-read-tree" has special-case logic that says: if you see 171a file that matches in all respects in the following states, it 172"collapses" back to "stage0": 173 174 - stage 2 and 3 are the same; take one or the other (it makes no 175 difference - the same work has been done on stage 2 and 3) 176 177 - stage 1 and stage 2 are the same and stage 3 is different; take 178 stage 3 (some work has been done on stage 3) 179 180 - stage 1 and stage 3 are the same and stage 2 is different take 181 stage 2 (some work has been done on stage 2) 182 183The "git-write-tree" command refuses to write a nonsensical tree, and it 184will complain about unmerged entries if it sees a single entry that is not 185stage 0. 186 187Ok, this all sounds like a collection of totally nonsensical rules, 188but it's actually exactly what you want in order to do a fast 189merge. The different stages represent the "result tree" (stage 0, aka 190"merged"), the original tree (stage 1, aka "orig"), and the two trees 191you are trying to merge (stage 2 and 3 respectively). 192 193The order of stages 1, 2 and 3 (hence the order of three 194<tree-ish> command line arguments) are significant when you 195start a 3-way merge with an index file that is already 196populated. Here is an outline of how the algorithm works: 197 198- if a file exists in identical format in all three trees, it will 199 automatically collapse to "merged" state by git-read-tree. 200 201- a file that has _any_ difference what-so-ever in the three trees 202 will stay as separate entries in the index. It's up to "porcelain 203 policy" to determine how to remove the non-0 stages, and insert a 204 merged version. 205 206- the index file saves and restores with all this information, so you 207 can merge things incrementally, but as long as it has entries in 208 stages 1/2/3 (ie "unmerged entries") you can't write the result. So 209 now the merge algorithm ends up being really simple: 210 211 * you walk the index in order, and ignore all entries of stage 0, 212 since they've already been done. 213 214 * if you find a "stage1", but no matching "stage2" or "stage3", you 215 know it's been removed from both trees (it only existed in the 216 original tree), and you remove that entry. 217 218 * if you find a matching "stage2" and "stage3" tree, you remove one 219 of them, and turn the other into a "stage0" entry. Remove any 220 matching "stage1" entry if it exists too. .. all the normal 221 trivial rules .. 222 223You would normally use "git-merge-index" with supplied 224"git-merge-one-file" to do this last step. The script 225does not touch the files in the work tree, and the entire merge 226happens in the index file. In other words, there is no need to 227worry about what is in the working directory, since it is never 228shown and never used. 229 230When you start a 3-way merge with an index file that is already 231populated, it is assumed that it represents the state of the 232files in your work tree, and you can even have files with 233changes unrecorded in the index file. It is further assumed 234that this state is "derived" from the stage 2 tree. The 3-way 235merge refuses to run if it finds an entry in the original index 236file that does not match stage 2. 237 238This is done to prevent you from losing your work-in-progress 239changes. To illustrate, suppose you start from what has been 240commited last to your repository: 241 242 $ JC=`git-rev-parse --verify "HEAD^0"` 243 $ git-checkout-index -f -u -a $JC 244 245You do random edits, without running git-update-index. And then 246you notice that the tip of your "upstream" tree has advanced 247since you pulled from him: 248 249 $ git-fetch rsync://.... linus 250 $ LT=`cat .git/MERGE_HEAD` 251 252Your work tree is still based on your HEAD ($JC), but you have 253some edits since. Three-way merge makes sure that you have not 254added or modified index entries since $JC, and if you haven't, 255then does the right thing. So with the following sequence: 256 257 $ git-read-tree -m -u `git-merge-base $JC $LT` $JC $LT 258 $ git-merge-index git-merge-one-file -a 259 $ echo "Merge with Linus" | \ 260 git-commit-tree `git-write-tree` -p $JC -p $LT 261 262what you would commit is a pure merge between $JC and LT without 263your work-in-progress changes, and your work tree would be 264updated to the result of the merge. 265 266 267See Also 268-------- 269gitlink:git-write-tree[1]; gitlink:git-ls-files[1] 270 271 272Author 273------ 274Written by Linus Torvalds <torvalds@osdl.org> 275 276Documentation 277-------------- 278Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. 279 280GIT 281--- 282Part of the gitlink:git[7] suite 283