@matheusbsbs / matheus-bagliano / commits / ffb1a4bed5
Fork 0

Documentation: Describe merge operation a bit better.

In git-merge documentation, add a section to describe what happens to the index and working tree during merge, and what their cleanliness requirements are before the merge. Signed-off-by: Junio C Hamano <junkio@cox.net>

Junio C Hamano committed Nov 28, 2005 at 22:54 UTC ffb1a4bed55534e276a0e4fc7dc1c94d17be8579
1 file changed +95
Documentation/git-merge.txt
+95
@@ -37,6 +37,101 @@ include::merge-options.txt[]
37 include::merge-strategies.txt[]
38
39
40 +HOW MERGE WORKS
41 +---------------
42 +
43 +A merge is always between the current `HEAD` and one or more
44 +remote branch heads, and the index file must exactly match the
45 +tree of `HEAD` commit (i.e. the contents of the last commit) when
46 +it happens. In other words, `git-diff --cached HEAD` must
47 +report no changes.
48 +
49 +[NOTE]
50 +This is a bit of lie. In certain special cases, your index are
51 +allowed to be different from the tree of `HEAD` commit. The most
52 +notable case is when your `HEAD` commit is already ahead of what
53 +is being merged, in which case your index can have arbitrary
54 +difference from your `HEAD` commit. Otherwise, your index entries
55 +are allowed have differences from your `HEAD` commit that match
56 +the result of trivial merge (e.g. you received the same patch
57 +from external source to produce the same result as what you are
58 +merging). For example, if a path did not exist in the common
59 +ancestor and your head commit but exists in the tree you are
60 +merging into your repository, and if you already happen to have
61 +that path exactly in your index, the merge does not have to
62 +fail.
63 +
64 +Otherwise, merge will refuse to do any harm to your repository
65 +(that is, it may fetch the objects from remote, and it may even
66 +update the local branch used to keep track of the remote branch
67 +with `git pull remote rbranch:lbranch`, but your working tree,
68 +`.git/HEAD` pointer and index file are left intact).
69 +
70 +You may have local modifications in the working tree files. In
71 +other words, `git-diff` is allowed to report changes.
72 +However, the merge uses your working tree as the working area,
73 +and in order to prevent the merge operation from losing such
74 +changes, it makes sure that they do not interfere with the
75 +merge. Those complex tables in read-tree documentation define
76 +what it means for a path to "interfere with the merge". And if
77 +your local modifications interfere with the merge, again, it
78 +stops before touching anything.
79 +
80 +So in the above two "failed merge" case, you do not have to
81 +worry about lossage of data --- you simply were not ready to do
82 +a merge, so no merge happened at all. You may want to finish
83 +whatever you were in the middle of doing, and retry the same
84 +pull after you are done and ready.
85 +
86 +When things cleanly merge, these things happen:
87 +
88 +1. the results are updated both in the index file and in your
89 + working tree,
90 +2. index file is written out as a tree,
91 +3. the tree gets committed, and
92 +4. the `HEAD` pointer gets advanced.
93 +
94 +Because of 2., we require that the original state of the index
95 +file to match exactly the current `HEAD` commit; otherwise we
96 +will write out your local changes already registered in your
97 +index file along with the merge result, which is not good.
98 +Because 1. involves only the paths different between your
99 +branch and the remote branch you are pulling from during the
100 +merge (which is typically a fraction of the whole tree), you can
101 +have local modifications in your working tree as long as they do
102 +not overlap with what the merge updates.
103 +
104 +When there are conflicts, these things happen:
105 +
106 +1. `HEAD` stays the same.
107 +
108 +2. Cleanly merged paths are updated both in the index file and
109 + in your working tree.
110 +
111 +3. For conflicting paths, the index file records the version
112 + from `HEAD`. The working tree files have the result of
113 + "merge" program; i.e. 3-way merge result with familiar
114 + conflict markers `<<< === >>>`.
115 +
116 +4. No other changes are done. In particular, the local
117 + modifications you had before you started merge will stay the
118 + same and the index entries for them stay as they were,
119 + i.e. matching `HEAD`.
120 +
121 +After seeing a conflict, you can do two things:
122 +
123 + * Decide not to merge. The only clean-up you need are to reset
124 + the index file to the `HEAD` commit to reverse 2. and to clean
125 + up working tree changes made by 2. and 3.; `git-reset` can
126 + be used for this.
127 +
128 + * Resolve the conflicts. `git-diff` would report only the
129 + conflicting paths because of the above 2. and 3.. Edit the
130 + working tree files into a desirable shape, `git-update-index`
131 + them, to make the index file contain what the merge result
132 + should be, and run `git-commit` to commit the result.
133 +
134 +
135 SEE ALSO
136 --------
137 gitlink:git-fmt-merge-msg[1], gitlink:git-pull[1]