Skip to content

Commit 9ba929e

Browse files
spearcespearce
committed
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
2 parents c11c7a5 + 3407a7a commit 9ba929e

File tree

13 files changed

+685
-119
lines changed

13 files changed

+685
-119
lines changed

‎Documentation/config.txt‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -927,6 +927,14 @@ man.<tool>.path::
927927
Override the path for the given tool that may be used to
928928
display help in the 'man' format. See linkgit:git-help[1].
929929

930+
merge.conflictstyle::
931+
Specify the style in which conflicted hunks are written out to
932+
working tree files upon merge. The default is "merge", which
933+
shows `<<<<<<<` conflict marker, change made by one side,
934+
`=======` marker, change made by the other side, and then
935+
`>>>>>>>` marker. An alternate style, "diff3", adds `|||||||`
936+
marker and the original text before `=======` marker.
937+
930938
mergetool.<tool>.path::
931939
Override the path for the given tool. This is useful in case
932940
your tool is not in the PATH.

‎Documentation/git-checkout.txt‎

Lines changed: 34 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ SYNOPSIS
99
--------
1010
[verse]
1111
'git checkout' [-q] [-f] [--track | --no-track] [-b <new_branch> [-l]] [-m] [<branch>]
12-
'git checkout' [<tree-ish>] [--] <paths>...
12+
'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <paths>...
1313

1414
DESCRIPTION
1515
-----------
@@ -27,23 +27,38 @@ the first namespace level.
2727

2828
When <paths> are given, this command does *not* switch
2929
branches. It updates the named paths in the working tree from
30-
the index file (i.e. it runs `git checkout-index -f -u`), or
31-
from a named commit. In
32-
this case, the `-f` and `-b` options are meaningless and giving
30+
the index file, or from a named commit. In
31+
this case, the `-b` options is meaningless and giving
3332
either of them results in an error. <tree-ish> argument can be
3433
used to specify a specific tree-ish (i.e. commit, tag or tree)
3534
to update the index for the given paths before updating the
3635
working tree.
3736

37+
The index may contain unmerged entries after a failed merge. By
38+
default, if you try to check out such an entry from the index, the
39+
checkout operation will fail and nothing will be checked out.
40+
Using -f will ignore these unmerged entries. The contents from a
41+
specific side of the merge can be checked out of the index by
42+
using --ours or --theirs. With -m, changes made to the working tree
43+
file can be discarded to recreate the original conflicted merge result.
3844

3945
OPTIONS
4046
-------
4147
-q::
4248
Quiet, suppress feedback messages.
4349

4450
-f::
45-
Proceed even if the index or the working tree differs
46-
from HEAD. This is used to throw away local changes.
51+
When switching branches, proceed even if the index or the
52+
working tree differs from HEAD. This is used to throw away
53+
local changes.
54+
+
55+
When checking out paths from the index, do not fail upon unmerged
56+
entries; instead, unmerged entries are ignored.
57+
58+
--ours::
59+
--theirs::
60+
When checking out paths from the index, check out stage #2
61+
('ours') or #3 ('theirs') for unmerged paths.
4762

4863
-b::
4964
Create a new branch named <new_branch> and start it at
@@ -84,7 +99,9 @@ exlicitly give a name with '-b' in such a case.
8499
based sha1 expressions such as "<branchname>@\{yesterday}".
85100

86101
-m::
87-
If you have local modifications to one or more files that
102+
--merge::
103+
When switching branches,
104+
if you have local modifications to one or more files that
88105
are different between the current branch and the branch to
89106
which you are switching, the command refuses to switch
90107
branches in order to preserve your modifications in context.
@@ -96,6 +113,16 @@ When a merge conflict happens, the index entries for conflicting
96113
paths are left unmerged, and you need to resolve the conflicts
97114
and mark the resolved paths with `git add` (or `git rm` if the merge
98115
should result in deletion of the path).
116+
+
117+
When checking out paths from the index, this option lets you recreate
118+
the conflicted merge in the specified paths.
119+
120+
--conflict=<style>::
121+
The same as --merge option above, but changes the way the
122+
conflicting hunks are presented, overriding the
123+
merge.conflictstyle configuration variable. Possible values are
124+
"merge" (default) and "diff3" (in addition to what is shown by
125+
"merge" style, shows the original contents).
99126

100127
<new_branch>::
101128
Name for the new branch.

‎Documentation/git-merge.txt‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -119,6 +119,71 @@ When there are conflicts, these things happen:
119119
same and the index entries for them stay as they were,
120120
i.e. matching `HEAD`.
121121

122+
HOW CONFLICTS ARE PRESENTED
123+
---------------------------
124+
125+
During a merge, the working tree files are updated to reflect the result
126+
of the merge. Among the changes made to the common ancestor's version,
127+
non-overlapping ones (that is, you changed an area of the file while the
128+
other side left that area intact, or vice versa) are incorporated in the
129+
final result verbatim. When both sides made changes to the same area,
130+
however, git cannot randomly pick one side over the other, and asks you to
131+
resolve it by leaving what both sides did to that area.
132+
133+
By default, git uses the same style as that is used by "merge" program
134+
from the RCS suite to present such a conflicted hunk, like this:
135+
136+
------------
137+
Here are lines that are either unchanged from the common
138+
ancestor, or cleanly resolved because only one side changed.
139+
<<<<<<< yours:sample.txt
140+
Conflict resolution is hard;
141+
let's go shopping.
142+
=======
143+
Git makes conflict resolution easy.
144+
>>>>>>> theirs:sample.txt
145+
And here is another line that is cleanly resolved or unmodified.
146+
------------
147+
148+
The area a pair of conflicting changes happened is marked with markers
149+
"`<<<<<<<`", "`=======`", and "`>>>>>>>`". The part before the "`=======`"
150+
is typically your side, and the part after it is typically their side.
151+
152+
The default format does not show what the original said in the conflicted
153+
area. You cannot tell how many lines are deleted and replaced with the
154+
Barbie's remark by your side. The only thing you can tell is that your
155+
side wants to say it is hard and you'd prefer to go shopping, while the
156+
other side wants to claim it is easy.
157+
158+
An alternative style can be used by setting the "merge.conflictstyle"
159+
configuration variable to "diff3". In "diff3" style, the above conflict
160+
may look like this:
161+
162+
------------
163+
Here are lines that are either unchanged from the common
164+
ancestor, or cleanly resolved because only one side changed.
165+
<<<<<<< yours:sample.txt
166+
Conflict resolution is hard;
167+
let's go shopping.
168+
|||||||
169+
Conflict resolution is hard.
170+
=======
171+
Git makes conflict resolution easy.
172+
>>>>>>> theirs:sample.txt
173+
And here is another line that is cleanly resolved or unmodified.
174+
------------
175+
176+
In addition to the "`<<<<<<<`", "`=======`", and "`>>>>>>>`" markers, it uses
177+
another "`|||||||`" marker that is followed by the original text. You can
178+
tell that the original just stated a fact, and your side simply gave in to
179+
that statement and gave up, while the other side tried to have a more
180+
positive attitude. You can sometimes come up with a better resolution by
181+
viewing the original.
182+
183+
184+
HOW TO RESOLVE CONFLICTS
185+
------------------------
186+
122187
After seeing a conflict, you can do two things:
123188

124189
* Decide not to merge. The only clean-up you need are to reset

0 commit comments

Comments
 (0)