Merge branch 'jc/better-conflict-resolution'

* jc/better-conflict-resolution:
  Fix AsciiDoc errors in merge documentation
  git-merge documentation: describe how conflict is presented
  checkout --conflict=<style>: recreate merge in a non-default style
  checkout -m: recreate merge when checking out of unmerged index
  git-merge-recursive: learn to honor merge.conflictstyle
  merge.conflictstyle: choose between "merge" and "diff3 -m" styles
  rerere: understand "diff3 -m" style conflicts with the original
  rerere.c: use symbolic constants to keep track of parsing states
  xmerge.c: "diff3 -m" style clips merge reduction level to EAGER or less
  xmerge.c: minimum readability fixups
  xdiff-merge: optionally show conflicts in "diff3 -m" style
  xdl_fill_merge_buffer(): separate out a too deeply nested function
  checkout --ours/--theirs: allow checking out one side of a conflicting merge
  checkout -f: allow ignoring unmerged paths when checking out of the index

Conflicts:
	Documentation/git-checkout.txt
	builtin-checkout.c
	builtin-merge-recursive.c
	t/t7201-co.sh

1 files changed, 65 insertions, 0 deletions

diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt
index 685e1fed58..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