Documentation: talk about guts of merge in tutorial.
While discussing Jon's ASCII art on merge operations with him, I realized that the tutorial stops talking about the plumbing details halfway. So fill in the gory details, and update the examples to use 'git-merge', not 'git-resolve'. Signed-off-by: Junio C Hamano <junkio@cox.net>
Junio C Hamano committed
Nov 6, 2005 at 23:29 UTC
44760f1d559ae2087e53be6971ad4f1a8f18f1d7
1 file changed
+155
-8
[mybranch^] New day.
renamed
+155
-8
@@ -301,7 +301,7 @@ all with a sequence of simple shell commands:
301
------------------------------------------------
302
tree=$(git-write-tree)
303
commit=$(echo 'Initial commit' | git-commit-tree $tree)
304
-git-update-ref HEAD $(commit)
304
+git-update-ref HEAD $commit
305
------------------------------------------------
306
307
which will say:
@@ -836,14 +836,14 @@ source.
836
Anyway, let's exit `gitk` (`^Q` or the File menu), and decide that we want
837
to merge the work we did on the `mybranch` branch into the `master`
838
branch (which is currently our `HEAD` too). To do that, there's a nice
839
-script called `git resolve`, which wants to know which branches you want
839
+script called `git merge`, which wants to know which branches you want
840
to resolve and what the merge is all about:
841
842
------------
843
-git resolve HEAD mybranch "Merge work in mybranch"
843
+git merge "Merge work in mybranch" HEAD mybranch
844
------------
845
846
-where the third argument is going to be used as the commit message if
846
+where the first argument is going to be used as the commit message if
847
the merge can be resolved automatically.
848
849
Now, in this case we've intentionally created a situation where the
@@ -851,12 +851,14 @@ merge will need to be fixed up by hand, though, so git will do as much
851
of it as it can automatically (which in this case is just merge the `example`
852
file, which had no differences in the `mybranch` branch), and say:
853
854
- Simple merge failed, trying Automatic merge
855
- Auto-merging hello.
854
+ Trying really trivial in-index merge...
855
+ fatal: Merge requires file-level merging
856
+ Nope.
857
+ ...
858
merge: warning: conflicts during merge
859
ERROR: Merge conflict in hello.
860
fatal: merge program failed
859
- Automatic merge failed, fix up by hand
861
+ Automatic merge failed/prevented; fix up by hand
862
863
which is way too verbose, but it basically tells you that it failed the
864
really trivial merge ("Simple merge") and did an "Automatic merge"
@@ -928,7 +930,7 @@ resolve to get the "upstream changes" back to your branch.
930
931
------------
932
git checkout mybranch
931
-git resolve HEAD master "Merge upstream changes."
933
+git merge "Merge upstream changes." HEAD master
934
------------
935
936
This outputs something like this (the actual commit object names
@@ -1103,6 +1105,155 @@ the above are equivalent to:
1105
. `git pull http://www.kernel.org/pub/.../jgarzik/netdev-2.6.git e100`
1106
1107
1108
+How does the merge work?
1109
+------------------------
1110
+
1111
+We said this tutorial shows what plumbing does to help you cope
1112
+with the porcelain that isn't flushing, but we so far did not
1113
+talk about how the merge really works. If you are following
1114
+this tutorial the first time, I'd suggest to skip to "Publishing
1115
+your work" section and come back here later.
1116
+
1117
+OK, still with me? To give us an example to look at, let's go
1118
+back to the earlier repository with "hello" and "example" file,
1119
+and bring ourselves back to the pre-merge state:
1120
+
1121
+------------
1122
+$ git show-branch --more=3 master mybranch
1123
+! [master] Merge work in mybranch
1124
+ * [mybranch] Merge work in mybranch
1125
+--
1126
+------------
1127
+
1128
+Remember, before running `git merge`, our `master` head was at
1129
+"Some fun." commit, while our `mybranch` head was at "Some
1130
+work." commit.
1131
+
1132
+------------
1133
+$ git checkout mybranch
1134
+$ git reset --hard master^2
1135
+$ git checkout master
1136
+$ git reset --hard master^
1137
+------------
1138
+
1139
+After rewinding, the commit structure should look like this:
1140
+
1141
+------------
1142
+$ git show-branch
1143
+* [master] Some fun.
1144
+ ! [mybranch] Some work.
1145
+--
1146
+ + [mybranch] Some work.
1147
++ [master] Some fun.
1148
+------------
1149
+
1150
+Now we are ready to experiment with the merge by hand.
1151
+
1152
+`git merge` command, when merging two branches, uses 3-way merge
1153
+algorithm. First, it finds the common ancestor between them.
1154
+The command it uses is `git-merge-base`:
1155
+
1156
+------------
1157
+$ mb=$(git-merge-base HEAD mybranch)
1158
+------------
1159
+
1160
+The command writes the commit object name of the common ancestor
1161
+to the standard output, so we captured its output to a variable,
1162
+because we will be using it in the next step. BTW, the common
1163
+ancestor commit is the "New day." commit in this case. You can
1164
+tell it by:
1165
+
1166
+------------
1167
+$ git-name-rev $mb
1168
+my-first-tag
1169
+------------
1170
+
1171
+After finding out a common ancestor commit, the second step is
1172
+this:
1173
+
1174
+------------
1175
+$ git-read-tree -m -u $mb HEAD mybranch
1176
+------------
1177
+
1178
+This is the same `git-read-tree` command we have already seen,
1179
+but it takes three trees, unlike previous examples. This reads
1180
+the contents of each tree into different 'stage' in the index
1181
+file (the first tree goes to stage 1, the second stage 2,
1182
+etc.). After reading three trees into three stages, the paths
1183
+that are the same in all three stages are 'collapsed' into stage
1184
+0. Also paths that are the same in two of three stages are
1185
+collapsed into stage 0, taking the SHA1 from either stage 2 or
1186
+stage 3, whichever is different from stage 1 (i.e. only one side
1187
+changed from the common ancestor).
1188
+
1189
+After 'collapsing' operation, paths that are different in three
1190
+trees are left in non-zero stages. At this point, you can
1191
+inspect the index file with this command:
1192
+
1193
+------------
1194
+$ git-ls-files --stage
1195
+100644 7f8b141b65fdcee47321e399a2598a235a032422 0 example
1196
+100644 263414f423d0e4d70dae8fe53fa34614ff3e2860 1 hello
1197
+100644 06fa6a24256dc7e560efa5687fa84b51f0263c3a 2 hello
1198
+100644 cc44c73eb783565da5831b4d820c962954019b69 3 hello
1199
+------------
1200
+
1201
+In our example of only two files, we did not have unchanged
1202
+files so only 'example' resulted in collapsing, but in real-life
1203
+large projects, only small number of files change in one commit,
1204
+and this 'collapsing' tends to trivially merge most of the paths
1205
+fairly quickly, leaving only the real changes in non-zero stages.
1206
+
1207
+To look at only non-zero stages, use `\--unmerged` flag:
1208
+
1209
+------------
1210
+$ git-ls-files --unmerged
1211
+100644 263414f423d0e4d70dae8fe53fa34614ff3e2860 1 hello
1212
+100644 06fa6a24256dc7e560efa5687fa84b51f0263c3a 2 hello
1213
+100644 cc44c73eb783565da5831b4d820c962954019b69 3 hello
1214
+------------
1215
+
1216
+The next step of merging is to merge these three versions of the
1217
+file, using 3-way merge. This is done by giving
1218
+`git-merge-one-file` command as one of the arguments to
1219
+`git-merge-index` command:
1220
+
1221
+------------
1222
+$ git-merge-index git-merge-one-file hello
1223
+Auto-merging hello.
1224
+merge: warning: conflicts during merge
1225
+ERROR: Merge conflict in hello.
1226
+fatal: merge program failed
1227
+------------
1228
+
1229
+`git-merge-one-file` script is called with parameters to
1230
+describe those three versions, and is responsible to leave the
1231
+merge results in the working tree and register it in the index
1232
+file. It is a fairly straightforward shell script, and
1233
+eventually calls `merge` program from RCS suite to perform the
1234
+file-level 3-way merge. In this case, `merge` detects
1235
+conflicts, and the merge result with conflict marks is left in
1236
+the working tree, while the index file is updated with the
1237
+version from the current branch (this is to make `git diff`
1238
+useful after this step). This can be seen if you run `ls-files
1239
+--stage` again at this point:
1240
+
1241
+------------
1242
+$ git-ls-files --stage
1243
+100644 7f8b141b65fdcee47321e399a2598a235a032422 0 example
1244
+100644 06fa6a24256dc7e560efa5687fa84b51f0263c3a 0 hello
1245
+------------
1246
+
1247
+As you can see, there is no unmerged paths in the index file.
1248
+This is the state of the index file and the working file after
1249
+`git merge` returns control back to you, leaving the conflicting
1250
+merge for you to resolve.
1251
+
1252
+
1253
Publishing your work
1254
--------------------
1255