Documentation/git-read-tree.txt

   1 git-read-tree(1)
   2 ================
   3 v0.1, May 2005
   4
   5 NAME
   6 ----
   7 git-read-tree - Reads tree information into the directory cache
   8
   9
  10 SYNOPSIS
  11 --------
  12 'git-read-tree' (<tree-ish> | -m <tree-ish1> [<tree-ish2> <tree-ish3>])"
  13
  14 DESCRIPTION
  15 -----------
  16 Reads the tree information given by <tree> into the directory cache,
  17 but does not actually *update* any of the files it "caches". (see:
  18 git-checkout-cache)
  19
  20 Optionally, it can merge a tree into the cache or perform a 3-way
  21 merge.
  22
  23 Trivial merges are done by "git-read-tree" itself.  Only conflicting paths
  24 will be in unmerged state when "git-read-tree" returns.
  25
  26 OPTIONS
  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
  35 Merging
  36 -------
  37 If '-m' is specified, "git-read-tree" performs 2 kinds of merge, a single tree
  38 merge if only 1 tree is given or a 3-way merge if 3 trees are
  39 provided.
  40
  41 Single Tree Merge
  42 ~~~~~~~~~~~~~~~~~
  43 If only 1 tree is specified, git-read-tree operates as if the user did not
  44 specify '-m', except that if the original cache has an entry for a
  45 given pathname; and the contents of the path matches with the tree
  46 being read, the stat info from the cache is used. (In other words, the
  47 cache's stat()s take precedence over the merged tree's)
  48
  49 That 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
  51 the stuff that really changed.
  52
  53 This is used to avoid unnecessary false hits when "git-diff-files" is
  54 run after git-read-tree.
  55
  56 3-Way Merge
  57 ~~~~~~~~~~~
  58 Each "index" entry has two bits worth of "stage" state. stage 0 is the
  59 normal one, and is the only one you'd see in any kind of normal use.
  60
  61 However, when you do "git-read-tree" with three trees, the "stage"
  62 starts out at 1.
  63
  64 This means that you can do
  65
  66         git-read-tree -m <tree1> <tree2> <tree3>
  67
  68 and 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
  72 Furthermore, "git-read-tree" has special-case logic that says: if you see
  73 a 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
  85 The "git-write-tree" command refuses to write a nonsensical tree, and it
  86 will complain about unmerged entries if it sees a single entry that is not
  87 stage 0.
  88
  89 Ok, this all sounds like a collection of totally nonsensical rules,
  90 but it's actually exactly what you want in order to do a fast
  91 merge. The different stages represent the "result tree" (stage 0, aka
  92 "merged"), the original tree (stage 1, aka "orig"), and the two trees
  93 you are trying to merge (stage 2 and 3 respectively).
  94
  95 In fact, the way "git-read-tree" works, it's entirely agnostic about how
  96 you assign the stages, and you could really assign them any which way,
  97 and 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
  99 sense to always consider stage 0 to be the "full merge" state).
 100
 101 So what happens? Try it out. Select the original tree, and two trees
 102 to 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
 130 Incidentally - it also means that you don't even have to have a
 131 separate subdirectory for this. All the information literally is in
 132 the index file, which is a temporary thing anyway. There is no need to
 133 worry about what is in the working directory, since it is never shown
 134 and never used.
 135
 136 See Also
 137 --------
 138 link:git-write-tree.html[git-write-tree]; link:git-ls-files.html[git-ls-files]
 139
 140
 141 Author
 142 ------
 143 Written by Linus Torvalds <torvalds@osdl.org>
 144
 145 Documentation
 146 --------------
 147 Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>.
 148
 149 GIT
 150 ---
 151 Part of the link:git.html[git] suite
 152