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