You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
152 lines
5.2 KiB
152 lines
5.2 KiB
git-read-tree(1) |
|
================ |
|
v0.1, May 2005 |
|
|
|
NAME |
|
---- |
|
git-read-tree - Reads tree information into the directory cache |
|
|
|
|
|
SYNOPSIS |
|
-------- |
|
'git-read-tree' (<tree-ish> | -m <tree-ish1> [<tree-ish2> <tree-ish3>])" |
|
|
|
DESCRIPTION |
|
----------- |
|
Reads the tree information given by <tree> into the directory cache, |
|
but does not actually *update* any of the files it "caches". (see: |
|
git-checkout-cache) |
|
|
|
Optionally, it can merge a tree into the cache or perform a 3-way |
|
merge. |
|
|
|
Trivial merges are done by "git-read-tree" itself. Only conflicting paths |
|
will be in unmerged state when "git-read-tree" returns. |
|
|
|
OPTIONS |
|
------- |
|
-m:: |
|
Perform a merge, not just a read |
|
|
|
<tree-ish#>:: |
|
The id of the tree object(s) to be read/merged. |
|
|
|
|
|
Merging |
|
------- |
|
If '-m' is specified, "git-read-tree" performs 2 kinds of merge, a single tree |
|
merge if only 1 tree is given or a 3-way merge if 3 trees are |
|
provided. |
|
|
|
Single Tree Merge |
|
~~~~~~~~~~~~~~~~~ |
|
If only 1 tree is specified, git-read-tree operates as if the user did not |
|
specify '-m', except that if the original cache has an entry for a |
|
given pathname; and the contents of the path matches with the tree |
|
being read, the stat info from the cache is used. (In other words, the |
|
cache's stat()s take precedence over the merged tree's) |
|
|
|
That means that if you do a "git-read-tree -m <newtree>" followed by a |
|
"git-checkout-cache -f -a", the "git-checkout-cache" only checks out |
|
the stuff that really changed. |
|
|
|
This is used to avoid unnecessary false hits when "git-diff-files" is |
|
run after git-read-tree. |
|
|
|
3-Way Merge |
|
~~~~~~~~~~~ |
|
Each "index" entry has two bits worth of "stage" state. stage 0 is the |
|
normal one, and is the only one you'd see in any kind of normal use. |
|
|
|
However, when you do "git-read-tree" with three trees, the "stage" |
|
starts out at 1. |
|
|
|
This means that you can do |
|
|
|
git-read-tree -m <tree1> <tree2> <tree3> |
|
|
|
and you will end up with an index with all of the <tree1> entries in |
|
"stage1", all of the <tree2> entries in "stage2" and all of the |
|
<tree3> entries in "stage3". |
|
|
|
Furthermore, "git-read-tree" has special-case logic that says: if you see |
|
a file that matches in all respects in the following states, it |
|
"collapses" back to "stage0": |
|
|
|
- stage 2 and 3 are the same; take one or the other (it makes no |
|
difference - the same work has been done on stage 2 and 3) |
|
|
|
- stage 1 and stage 2 are the same and stage 3 is different; take |
|
stage 3 (some work has been done on stage 3) |
|
|
|
- stage 1 and stage 3 are the same and stage 2 is different take |
|
stage 2 (some work has been done on stage 2) |
|
|
|
The "git-write-tree" command refuses to write a nonsensical tree, and it |
|
will complain about unmerged entries if it sees a single entry that is not |
|
stage 0. |
|
|
|
Ok, this all sounds like a collection of totally nonsensical rules, |
|
but it's actually exactly what you want in order to do a fast |
|
merge. The different stages represent the "result tree" (stage 0, aka |
|
"merged"), the original tree (stage 1, aka "orig"), and the two trees |
|
you are trying to merge (stage 2 and 3 respectively). |
|
|
|
In fact, the way "git-read-tree" works, it's entirely agnostic about how |
|
you assign the stages, and you could really assign them any which way, |
|
and the above is just a suggested way to do it (except since |
|
"git-write-tree" refuses to write anything but stage0 entries, it makes |
|
sense to always consider stage 0 to be the "full merge" state). |
|
|
|
So what happens? Try it out. Select the original tree, and two trees |
|
to merge, and look how it works: |
|
|
|
- if a file exists in identical format in all three trees, it will |
|
automatically collapse to "merged" state by the new git-read-tree. |
|
|
|
- a file that has _any_ difference what-so-ever in the three trees |
|
will stay as separate entries in the index. It's up to "script |
|
policy" to determine how to remove the non-0 stages, and insert a |
|
merged version. But since the index is always sorted, they're easy |
|
to find: they'll be clustered together. |
|
|
|
- the index file saves and restores with all this information, so you |
|
can merge things incrementally, but as long as it has entries in |
|
stages 1/2/3 (ie "unmerged entries") you can't write the result. So |
|
now the merge algorithm ends up being really simple: |
|
|
|
* you walk the index in order, and ignore all entries of stage 0, |
|
since they've already been done. |
|
|
|
* if you find a "stage1", but no matching "stage2" or "stage3", you |
|
know it's been removed from both trees (it only existed in the |
|
original tree), and you remove that entry. |
|
|
|
* if you find a matching "stage2" and "stage3" tree, you remove one |
|
of them, and turn the other into a "stage0" entry. Remove any |
|
matching "stage1" entry if it exists too. .. all the normal |
|
trivial rules .. |
|
|
|
Incidentally - it also means that you don't even have to have a |
|
separate subdirectory for this. All the information literally is in |
|
the index file, which is a temporary thing anyway. There is no need to |
|
worry about what is in the working directory, since it is never shown |
|
and never used. |
|
|
|
See Also |
|
-------- |
|
link:git-write-tree.html[git-write-tree]; link:git-ls-files.html[git-ls-files] |
|
|
|
|
|
Author |
|
------ |
|
Written by Linus Torvalds <torvalds@osdl.org> |
|
|
|
Documentation |
|
-------------- |
|
Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. |
|
|
|
GIT |
|
--- |
|
Part of the link:git.html[git] suite |
|
|
|
|