summaryrefslogtreecommitdiff
path: root/Documentation/git-merge.txt
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/git-merge.txt')
-rw-r--r--Documentation/git-merge.txt89
1 files changed, 83 insertions, 6 deletions
diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt
index 17a15acb07..1f30830d46 100644
--- a/Documentation/git-merge.txt
+++ b/Documentation/git-merge.txt
@@ -119,6 +119,71 @@ When there are conflicts, these things happen:
same and the index entries for them stay as they were,
i.e. matching `HEAD`.
+HOW CONFLICTS ARE PRESENTED
+---------------------------
+
+During a merge, the working tree files are updated to reflect the result
+of the merge. Among the changes made to the common ancestor's version,
+non-overlapping ones (that is, you changed an area of the file while the
+other side left that area intact, or vice versa) are incorporated in the
+final result verbatim. When both sides made changes to the same area,
+however, git cannot randomly pick one side over the other, and asks you to
+resolve it by leaving what both sides did to that area.
+
+By default, git uses the same style as that is used by "merge" program
+from the RCS suite to present such a conflicted hunk, like this:
+
+------------
+Here are lines that are either unchanged from the common
+ancestor, or cleanly resolved because only one side changed.
+<<<<<<< yours:sample.txt
+Conflict resolution is hard;
+let's go shopping.
+=======
+Git makes conflict resolution easy.
+>>>>>>> theirs:sample.txt
+And here is another line that is cleanly resolved or unmodified.
+------------
+
+The area a pair of conflicting changes happened is marked with markers
+"`<<<<<<<`", "`=======`", and "`>>>>>>>`". The part before the "`=======`"
+is typically your side, and the part after it is typically their side.
+
+The default format does not show what the original said in the conflicted
+area. You cannot tell how many lines are deleted and replaced with the
+Barbie's remark by your side. The only thing you can tell is that your
+side wants to say it is hard and you'd prefer to go shopping, while the
+other side wants to claim it is easy.
+
+An alternative style can be used by setting the "merge.conflictstyle"
+configuration variable to "diff3". In "diff3" style, the above conflict
+may look like this:
+
+------------
+Here are lines that are either unchanged from the common
+ancestor, or cleanly resolved because only one side changed.
+<<<<<<< yours:sample.txt
+Conflict resolution is hard;
+let's go shopping.
+|||||||
+Conflict resolution is hard.
+=======
+Git makes conflict resolution easy.
+>>>>>>> theirs:sample.txt
+And here is another line that is cleanly resolved or unmodified.
+------------
+
+In addition to the "`<<<<<<<`", "`=======`", and "`>>>>>>>`" markers, it uses
+another "`|||||||`" marker that is followed by the original text. You can
+tell that the original just stated a fact, and your side simply gave in to
+that statement and gave up, while the other side tried to have a more
+positive attitude. You can sometimes come up with a better resolution by
+viewing the original.
+
+
+HOW TO RESOLVE CONFLICTS
+------------------------
+
After seeing a conflict, you can do two things:
* Decide not to merge. The only clean-up you need are to reset
@@ -126,13 +191,25 @@ After seeing a conflict, you can do two things:
up working tree changes made by 2. and 3.; 'git-reset --hard' can
be used for this.
- * Resolve the conflicts. `git diff` would report only the
- conflicting paths because of the above 2. and 3.
- Edit the working tree files into a desirable shape
- ('git mergetool' can ease this task), 'git-add' or 'git-rm'
- them, to make the index file contain what the merge result
- should be, and run 'git-commit' to commit the result.
+ * Resolve the conflicts. Git will mark the conflicts in
+ the working tree. Edit the files into shape and
+ 'git-add' to the index. 'git-commit' to seal the deal.
+
+You can work through the conflict with a number of tools:
+
+ * Use a mergetool. 'git mergetool' to launch a graphical
+ mergetool which will work you through the merge.
+
+ * Look at the diffs. 'git diff' will show a three-way diff,
+ highlighting changes from both the HEAD and remote versions.
+
+ * Look at the diffs on their own. 'git log --merge -p <path>'
+ will show diffs first for the HEAD version and then the
+ remote version.
+ * Look at the originals. 'git show :1:filename' shows the
+ common ancestor, 'git show :2:filename' shows the HEAD
+ version and 'git show :3:filename' shows the remote version.
SEE ALSO
--------