git-merge-tree.txt: add a section on potentional usage mistakes
Signed-off-by: Elijah Newren <newren@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Elijah Newren committed
Jun 18, 2022 at 00:21 UTC
7260e87248e743b197d34c1caf3949ae4fa3bc12
1 file changed
+53
Documentation/git-merge-tree.txt
+53
@@ -156,6 +156,59 @@ with linkgit:git-merge[1]:
156
* any messages that would have been printed to stdout (the
157
<<IM,Informational messages>>)
158
159
+MISTAKES TO AVOID
160
+-----------------
161
+
162
+Do NOT look through the resulting toplevel tree to try to find which
163
+files conflict; parse the <<CFI,Conflicted file info>> section instead.
164
+Not only would parsing an entire tree be horrendously slow in large
165
+repositories, there are numerous types of conflicts not representable by
166
+conflict markers (modify/delete, mode conflict, binary file changed on
167
+both sides, file/directory conflicts, various rename conflict
168
+permutations, etc.)
169
+
170
+Do NOT interpret an empty <<CFI,Conflicted file info>> list as a clean
171
+merge; check the exit status. A merge can have conflicts without having
172
+individual files conflict (there are a few types of directory rename
173
+conflicts that fall into this category, and others might also be added
174
+in the future).
175
+
176
+Do NOT attempt to guess or make the user guess the conflict types from
177
+the <<CFI,Conflicted file info>> list. The information there is
178
+insufficient to do so. For example: Rename/rename(1to2) conflicts (both
179
+sides renamed the same file differently) will result in three different
180
+file having higher order stages (but each only has one higher order
181
+stage), with no way (short of the <<IM,Informational messages>> section)
182
+to determine which three files are related. File/directory conflicts
183
+also result in a file with exactly one higher order stage.
184
+Possibly-involved-in-directory-rename conflicts (when
185
+"merge.directoryRenames" is unset or set to "conflicts") also result in
186
+a file with exactly one higher order stage. In all cases, the
187
+<<IM,Informational messages>> section has the necessary info, though it
188
+is not designed to be machine parseable.
189
+
190
+Do NOT assume that each paths from <<CFI,Conflicted file info>>, and
191
+the logical conflicts in the <<IM,Informational messages>> have a
192
+one-to-one mapping, nor that there is a one-to-many mapping, nor a
193
+many-to-one mapping. Many-to-many mappings exist, meaning that each
194
+path can have many logical conflict types in a single merge, and each
195
+logical conflict type can affect many paths.
196
+
197
+Do NOT assume all filenames listed in the <<IM,Informational messages>>
198
+section had conflicts. Messages can be included for files that have no
199
+conflicts, such as "Auto-merging <file>".
200
+
201
+AVOID taking the OIDS from the <<CFI,Conflicted file info>> and
202
+re-merging them to present the conflicts to the user. This will lose
203
+information. Instead, look up the version of the file found within the
204
+<<OIDTLT,OID of toplevel tree>> and show that instead. In particular,
205
+the latter will have conflict markers annotated with the original
206
+branch/commit being merged and, if renames were involved, the original
207
+filename. While you could include the original branch/commit in the
208
+conflict marker annotations when re-merging, the original filename is
209
+not available from the <<CFI,Conflicted file info>> and thus you would
210
+be losing information that might help the user resolve the conflict.
211
+
212
[[DEPMERGE]]
213
DEPRECATED DESCRIPTION
214
----------------------