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