Documentation/git-read-tree: clarify 2-tree merge
Clarify the description of the 2-tree merge by defining the terms which are used in the table, and by applying some small linguistic changes. Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
This commit is contained in:
parent
71928f7f11
commit
7325283987
@ -130,7 +130,7 @@ 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 index has an entry for a
|
||||
given pathname, and the contents of the path matches with the tree
|
||||
given pathname, and the contents of the path match with the tree
|
||||
being read, the stat info from the index is used. (In other words, the
|
||||
index's stat()s take precedence over the merged tree's).
|
||||
|
||||
@ -154,22 +154,24 @@ When two trees are specified, the user is telling 'git read-tree'
|
||||
the following:
|
||||
|
||||
1. The current index and work tree is derived from $H, but
|
||||
the user may have local changes in them since $H;
|
||||
the user may have local changes in them since $H.
|
||||
|
||||
2. The user wants to fast-forward to $M.
|
||||
|
||||
In this case, the `git read-tree -m $H $M` command makes sure
|
||||
that no local change is lost as the result of this "merge".
|
||||
Here are the "carry forward" rules:
|
||||
Here are the "carry forward" rules, where "I" denotes the index,
|
||||
"clean" means that index and work tree coincide, and "exists"/"nothing"
|
||||
refer to the presence of a path in the specified commit:
|
||||
|
||||
I (index) H M Result
|
||||
I H M Result
|
||||
-------------------------------------------------------
|
||||
0 nothing nothing nothing (does not happen)
|
||||
1 nothing nothing exists use M
|
||||
2 nothing exists nothing remove path from index
|
||||
3 nothing exists exists, use M if "initial checkout"
|
||||
3 nothing exists exists, use M if "initial checkout",
|
||||
H == M keep index otherwise
|
||||
exists fail
|
||||
exists, fail
|
||||
H != M
|
||||
|
||||
clean I==H I==M
|
||||
@ -187,7 +189,7 @@ Here are the "carry forward" rules:
|
||||
12 yes no N/A exists nothing fail
|
||||
13 no no N/A exists nothing fail
|
||||
|
||||
clean (H=M)
|
||||
clean (H==M)
|
||||
------
|
||||
14 yes exists exists keep index
|
||||
15 no exists exists keep index
|
||||
@ -202,26 +204,26 @@ Here are the "carry forward" rules:
|
||||
21 no yes no exists exists fail
|
||||
|
||||
In all "keep index" cases, the index entry stays as in the
|
||||
original index file. If the entry were not up to date,
|
||||
original index file. If the entry is not up to date,
|
||||
'git read-tree' keeps the copy in the work tree intact when
|
||||
operating under the -u flag.
|
||||
|
||||
When this form of 'git read-tree' returns successfully, you can
|
||||
see what "local changes" you made are carried forward by running
|
||||
see which of the "local changes" that you made were carried forward by running
|
||||
`git diff-index --cached $M`. Note that this does not
|
||||
necessarily match `git diff-index --cached $H` would have
|
||||
necessarily match what `git diff-index --cached $H` would have
|
||||
produced before such a two tree merge. This is because of cases
|
||||
18 and 19 --- if you already had the changes in $M (e.g. maybe
|
||||
you picked it up via e-mail in a patch form), `git diff-index
|
||||
--cached $H` would have told you about the change before this
|
||||
merge, but it would not show in `git diff-index --cached $M`
|
||||
output after two-tree merge.
|
||||
output after the two-tree merge.
|
||||
|
||||
Case #3 is slightly tricky and needs explanation. The result from this
|
||||
Case 3 is slightly tricky and needs explanation. The result from this
|
||||
rule logically should be to remove the path if the user staged the removal
|
||||
of the path and then switching to a new branch. That however will prevent
|
||||
the initial checkout from happening, so the rule is modified to use M (new
|
||||
tree) only when the contents of the index is empty. Otherwise the removal
|
||||
tree) only when the content of the index is empty. Otherwise the removal
|
||||
of the path is kept as long as $H and $M are the same.
|
||||
|
||||
3-Way Merge
|
||||
|
Loading…
Reference in New Issue
Block a user