1git-read-tree(1) 2================ 3v0.1, May 2005 4 5NAME 6---- 7git-read-tree - Reads tree information into the directory cache 8 9 10SYNOPSIS 11-------- 12'git-read-tree' (<tree-ish> | -m <tree-ish1> [<tree-ish2> <tree-ish3>])" 13 14DESCRIPTION 15----------- 16Reads the tree information given by <tree> into the directory cache, 17but does not actually *update* any of the files it "caches". (see: 18git-checkout-cache) 19 20Optionally, it can merge a tree into the cache or perform a 3-way 21merge. 22 23Trivial merges are done by "git-read-tree" itself. Only conflicting paths 24will be in unmerged state when "git-read-tree" returns. 25 26OPTIONS 27------- 28-m:: 29 Perform a merge, not just a read 30 31<tree-ish#>:: 32 The id of the tree object(s) to be read/merged. 33 34 35Merging 36------- 37If '-m' is specified, "git-read-tree" performs 2 kinds of merge, a single tree 38merge if only 1 tree is given or a 3-way merge if 3 trees are 39provided. 40 41Single Tree Merge 42~~~~~~~~~~~~~~~~~ 43If only 1 tree is specified, git-read-tree operates as if the user did not 44specify '-m', except that if the original cache has an entry for a 45given pathname; and the contents of the path matches with the tree 46being read, the stat info from the cache is used. (In other words, the 47cache's stat()s take precedence over the merged tree's) 48 49That means that if you do a "git-read-tree -m <newtree>" followed by a 50"git-checkout-cache -f -a", the "git-checkout-cache" only checks out 51the stuff that really changed. 52 53This is used to avoid unnecessary false hits when "git-diff-files" is 54run after git-read-tree. 55 563-Way Merge 57~~~~~~~~~~~ 58Each "index" entry has two bits worth of "stage" state. stage 0 is the 59normal one, and is the only one you'd see in any kind of normal use. 60 61However, when you do "git-read-tree" with three trees, the "stage" 62starts out at 1. 63 64This means that you can do 65 66 git-read-tree -m <tree1> <tree2> <tree3> 67 68and you will end up with an index with all of the <tree1> entries in 69"stage1", all of the <tree2> entries in "stage2" and all of the 70<tree3> entries in "stage3". 71 72Furthermore, "git-read-tree" has special-case logic that says: if you see 73a file that matches in all respects in the following states, it 74"collapses" back to "stage0": 75 76 - stage 2 and 3 are the same; take one or the other (it makes no 77 difference - the same work has been done on stage 2 and 3) 78 79 - stage 1 and stage 2 are the same and stage 3 is different; take 80 stage 3 (some work has been done on stage 3) 81 82 - stage 1 and stage 3 are the same and stage 2 is different take 83 stage 2 (some work has been done on stage 2) 84 85The "git-write-tree" command refuses to write a nonsensical tree, and it 86will complain about unmerged entries if it sees a single entry that is not 87stage 0. 88 89Ok, this all sounds like a collection of totally nonsensical rules, 90but it's actually exactly what you want in order to do a fast 91merge. The different stages represent the "result tree" (stage 0, aka 92"merged"), the original tree (stage 1, aka "orig"), and the two trees 93you are trying to merge (stage 2 and 3 respectively). 94 95In fact, the way "git-read-tree" works, it's entirely agnostic about how 96you assign the stages, and you could really assign them any which way, 97and the above is just a suggested way to do it (except since 98"git-write-tree" refuses to write anything but stage0 entries, it makes 99sense to always consider stage 0 to be the "full merge" state). 100 101So what happens? Try it out. Select the original tree, and two trees 102to merge, and look how it works: 103 104- if a file exists in identical format in all three trees, it will 105 automatically collapse to "merged" state by the new git-read-tree. 106 107- a file that has _any_ difference what-so-ever in the three trees 108 will stay as separate entries in the index. It's up to "script 109 policy" to determine how to remove the non-0 stages, and insert a 110 merged version. But since the index is always sorted, they're easy 111 to find: they'll be clustered together. 112 113- the index file saves and restores with all this information, so you 114 can merge things incrementally, but as long as it has entries in 115 stages 1/2/3 (ie "unmerged entries") you can't write the result. So 116 now the merge algorithm ends up being really simple: 117 118 * you walk the index in order, and ignore all entries of stage 0, 119 since they've already been done. 120 121 * if you find a "stage1", but no matching "stage2" or "stage3", you 122 know it's been removed from both trees (it only existed in the 123 original tree), and you remove that entry. 124 125 * if you find a matching "stage2" and "stage3" tree, you remove one 126 of them, and turn the other into a "stage0" entry. Remove any 127 matching "stage1" entry if it exists too. .. all the normal 128 trivial rules .. 129 130Incidentally - it also means that you don't even have to have a 131separate subdirectory for this. All the information literally is in 132the index file, which is a temporary thing anyway. There is no need to 133worry about what is in the working directory, since it is never shown 134and never used. 135 136See Also 137-------- 138link:git-write-tree.html[git-write-tree]; link:git-ls-files.html[git-ls-files] 139 140 141Author 142------ 143Written by Linus Torvalds <torvalds@osdl.org> 144 145Documentation 146-------------- 147Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. 148 149GIT 150--- 151Part of the link:git.html[git] suite 152