Best Practices for Handling Git Merge Conflicts

information there is insufficient to do so. For example: Rename/rename(1to2) conflicts (both sides renamed the same file differently) will result in three different files having higher order stages (but each only has one higher order stage), with no way (short of the <<IM,Informational messages>> section) to determine which three files are related. File/directory conflicts also result in a file with exactly one higher order stage. Possibly-involved-in-directory-rename conflicts (when "merge.directoryRenames" is unset or set to "conflicts") also result in a file with exactly one higher order stage. In all cases, the <<IM,Informational messages>> section has the necessary info, though it is not designed to be machine parseable. Do NOT assume that each path from <<CFI,Conflicted file info>>, and the logical conflicts in the <<IM,Informational messages>> have a one-to-one mapping, nor that there is a one-to-many mapping, nor a many-to-one mapping. Many-to-many mappings exist, meaning that each path can have many logical conflict types in a single merge, and each logical conflict type can affect many paths. Do NOT assume all filenames listed in the <<IM,Informational messages>> section had conflicts. Messages can be included for files that have no conflicts, such as "Auto-merging <file>". AVOID taking the OIDS from the <<CFI,Conflicted file info>> and re-merging them to present the conflicts to the user. This will lose information. Instead, look up the version of the file found within the <<OIDTLT,OID of toplevel tree>> and show that instead. In particular, the latter will have conflict markers annotated with the original branch/commit being merged and, if renames were involved, the original filename. While you could include the original branch/commit in the conflict marker annotations when re-merging, the original filename is not available from the <<CFI,Conflicted file info>> and thus you would be losing information that might help the user resolve the conflict. [[DEPMERGE]] DEPRECATED DESCRIPTION ---------------------- Per the <<NEWMERGE,DESCRIPTION>> and unlike the rest of this documentation, this section describes the deprecated `--trivial-merge` mode. Other than the optional `--trivial-merge`, this mode accepts no options. This mode reads three tree-ish, and outputs trivial merge results and conflicting stages to the standard output in a semi-diff format. Since this was designed for higher level scripts to consume and merge the results back into the index, it omits entries that match <branch1>. The result of this second form is similar to what three-way 'git read-tree -m' does, but instead of storing the results in the index, the command outputs the entries to the standard output. This form not only has limited applicability (a trivial merge cannot handle content merges of individual files, rename detection, proper directory/file conflict handling, etc.), the output format is also difficult to work with, and it will generally be less performant than the first form even on successful merges (especially if working in large repositories). GIT --- Part of the linkgit:git[1] suite

The text outlines several best practices to avoid when handling git merge conflicts, including not assuming specific mappings between conflicted files and informational messages, not re-merging files to present conflicts, and not using the deprecated --trivial-merge mode, and instead describes the correct ways to handle conflicts and use the command output.