View source for Git/Workflow/Topic/Conflicts

{{ Historical }}

This page documents conflict resolution in a [[Git/Workflow/Topic|topic-based branchy workflow]].
__TOC__
Whenever two paths of development make different changes to the same initial content conflicts may occur when merging the branches.

= Single Integration Branch =

Consider two conflicting topic branches, ''topic'' and ''other-topic'', with the latter already merged to '''master''':

 ...o----o-------o  master
     \    \     /
      \    o---o  ''other-topic''
       \
        o----o  ''topic''

An attempt to merge ''topic'' into '''master''' will fail with conflicts.
One may use the following approaches to resolve the situation:
* Merge the [[#Topic-to-Single-Branch|topic to the branch]]
* Merge the [[#Branch-to-Topic|branch to the topic]]

== Topic-to-Single-Branch ==

If one performs the merge in a local work tree it is possible to simply resolve the conflicts and complete the merge:

 ...o----o-------o----o  master
     \    \     /    /
      \    o---o    /  ''other-topic''
       \           /
        o---------o  ''topic''

This approach does not work when using a [[Git/Workflow/Stage|topic stage]].
It cannot resolve the conflicts automatically and may print instructions to follow the [[#Branch-to-Topic|next approach]].

== Branch-to-Topic ==

Since a developer works on a topic branch locally one may simply merge the conflicting integration branch into the topic and resolve the conflicts:

 ...o----o-------o  master
     \    \     / \
      \    o---o   \  ''other-topic''
       \            \
        o----o-------o  ''topic''


In order to maintain a good [[Git/Workflow/Topic#History_Shape|shape of history]] one may then
merge the topic into the integration branch without allowing a fast-forward (<code>merge --no-ff</code>):

 ...o----o-------o-------o  master
     \    \     / \     /
      \    o---o   \   /  ''other-topic''
       \            \ /
        o----o-------o  ''topic''

Our [[Git/Workflow/Stage|topic stages]] use this approach when working with a single integration branch.

= Multiple Integration Branches =

In a workflow using multiple integration branches one must deal differently with conflicting topics.
Consider two conflicting topic branches, ''topic'' and ''other-topic'', with the latter already merged to '''next''':

 ...o----o  master
  .  \    \
   .  \    o---o ''topic''
    .  \
     .  o--------o  ''other-topic''
      .           \
       ............o  next

An attempt to merge ''topic'' into '''next''' will fail with conflicts.
One may use the following approaches to resolve the situation:
* Merge the [[#Topic-to-Branch|topic to the branch]]
* Merge [[#Topic-to-Topic|one topic into the other]]
* Merge both topics into a [[#Resolution_Topic|resolution topic]]
Note that one may ''not'' merge the [[#Branch-to-Topic|branch into the topic]] as in the single-integration-branch case because '''next''' may never be merged into a topic.

== Topic-to-Branch ==

If one performs the merge in a local work tree it is possible to simply resolve the conflicts and complete the merge:

 ...o----o  master
  .  \    \
   .  \    o--------o ''topic''
    .  \             \
     .  o--------o    \  ''other-topic''
      .           \    \
       ............o----o  next

However, the topics eventually must be merged to '''master'''.
Assume ''topic'' is merged first:

 ...o----o------------o  master
  .  \    \          /
   .  \    o--------o  ''topic''
    .  \             \
     .  o--------o    \  ''other-topic''
      .           \    \
       ............o----o  next

An attempt to merge ''other-topic'' into '''master''' will fail with the same conflicts!

 ...o----o------------o-----?  master
  .  \    \          /     /
   .  \    o--------o     /  ''topic''
    .  \             \   /
     .  o--------o----\--  ''other-topic''
      .           \    \
       ............o----o  next

The only branch that contains a resolution to these conflicts is '''next''', but that may not be merged to '''master'''.
Therefore one must resolve the conflicts a second time.

If the second resolution is not byte-for-byte identical to the first then the new '''master''' will not merge cleanly into '''next''':

 ...o----o------------o-----o  master
  .  \    \          /     / \
   .  \    o--------o     /   \  ''topic''
    .  \             \   /     \
     .  o--------o----\--       \  ''other-topic''
      .           \    \         \
       ............o----o---------?  next

Then one must resolve conflicts a third time!

This approach works with manual merging but requires care.
It does not work when using a [[Git/Workflow/Stage|topic stage]] that cannot resolve the conflicts automatically and may print instructions to follow the [[#Topic-to-Topic|next approach]].

== Topic-to-Topic ==

The [[Git/Workflow/Topic#Design|design]] of our topic-based workflow guarantees that work is always committed on topic branches and never directly on an integration branch.
If conflicts occur while merging a topic into an integration branch it means that the topic conflics with ''another topic'' that has already been merged.

One may manually merge the conflicting ''other-topic'' into one's own ''topic'' and resolve the conflicts:

 ...o----o  master
  .  \    \
   .  \    o---o---o  ''topic''
    .  \          /
     .  o--------o  ''other-topic''
      .           \
       ............o  next

Then ''topic'' will merge cleanly into '''next''':

 ...o----o  master
  .  \    \
   .  \    o---o---o  ''topic''
    .  \          / \
     .  o--------o   \  ''other-topic''
      .           \   \
       ............o---o next

Later ''topic'' may be merged cleanly into '''master''' to bring in both topics (or just ''topic'' if ''other-topic'' has already been merged):

 ...o----o-----------o  master
  .  \    \         /
   .  \    o---o---o  ''topic''
    .  \          / \
     .  o--------o   \  ''other-topic''
      .           \   \
       ............o---o next

Finally, '''master''' may be merged cleanly into '''next''':

 ...o----o-----------o  master
  .  \    \         / \
   .  \    o---o---o   \ ''topic''
    .  \          / \   \
     .  o--------o   \   \ ''other-topic''
      .           \   \   \
       ............o---o---o next

Note that this produces an artificial [[Git/Workflow/Topic#Dependent_Topic|topic dependency]] introduced by the conflict resolution commit.
See the [[#Resolution-Topic|next approach]] to avoid this problem.

== Resolution Topic ==

The [[#Topic-to-Topic|above approach]] introduces an artificial topic dependency because it asymmetrically favors one topic over another.
Instead one may use a third topic to resolve the conflicts.

One may start a new resolve/''topic''/''other-topic'' branch from ''topic'', merge ''other-topic'' into it, and resolve the conflicts:

 ...o----o  master
  .  \    \
   .  \    o---o  ''topic''
    .  \        \
     .  \        o  resolve/''topic''/''other-topic''
      .  \      /
       .  o----o  ''other-topic''
        .       \
         ........o  next

The resolution topic will merge cleanly into '''next''' to bring in the changes from ''topic'' through the conflict resolution commit:

 ...o----o  master
  .  \    \
   .  \    o---o  ''topic''
    .  \        \
     .  \        o  resolve/''topic''/''other-topic''
      .  \      / \
       .  o----o   \  ''other-topic''
        .       \   \
         ........o---o  next

Since ''topic'' and ''other-topic'' are still independent either may be merged to '''master''' first.
Assume ''topic'' is merged first:

 ...o----o-------o  master
  .  \    \     /
   .  \    o---o  ''topic''
    .  \        \
     .  \        o  resolve/''topic''/''other-topic''
      .  \      / \
       .  o----o   \  ''other-topic''
        .       \   \
         ........o---o  next

As [[#Topic-to-Branch|above]] an attempt to merge ''other-topic'' directly into '''master''' will fail with the original conflicts but now we have a topic containing the resolution commit independent of '''next'''.
One may merge the resolution topic to '''master''' to bring in the changes from ''other-topic'' and the conflict resolution:

 ...o----o-------o---o  master
  .  \    \     /   /
   .  \    o---o   /  ''topic''
    .  \        \ /
     .  \        o  resolve/''topic''/''other-topic''
      .  \      / \
       .  o----o   \  ''other-topic''
        .       \   \
         ........o---o  next

Finally, '''master''' may be merged cleanly into '''next''':

 ...o----o-------o---o  master
  .  \    \     /   / \
   .  \    o---o   /   \  ''topic''
    .  \        \ /     \
     .  \        o       \  resolve/''topic''/''other-topic''
      .  \      / \       \
       .  o----o   \       \  ''other-topic''
        .       \   \       \
         ........o---o-------o  next