Skip to main content
Version: 2024

Merging

Introduction to merging

When multiple developers or teams work on different features of an application simultaneously, additional branches can be made within a model for these features. Each feature can be developed separately and, as soon as it is completed, be combined (merged) with the model's origin branch. This way, a new feature can be developed and tested independently from the rest of the model.

Branches

For extensive information, see the Models and branches manual.

1. Create a merge session

When a branch is completed and tested, it can be merged back into its origin branch, for example, the MAIN branch.

When you create a merge session, changes (delta actions) are determined by comparing the situation at the origin point in time with the current point in time (that is, when the merge session was started). Data migration mappings are included in a merge, see Include data migration mappings during merge.

To create a merge session:

menu Models > Merging > tab Merging

  1. Execute the task Create merge session create merge session.
tip

In the fields Merge from and Merge into, you will initially only see active branches that have been marked as 'My branches', and their origin branch. This can make it easier to choose the correct branch to merge from and into. To merge from or into another branch, you can disable the prefilter My branches in the look-up popup.

Pop-up for creating a merge session

  1. Select the Model.
  2. Select which branch (Merge from) needs to be merged into another branch (Merge into).
  3. Select how to proceed with the branch after merging it into its origin.
    • Keep working in branch, perform reciprocal merge - Select this option to continue working in the branch. Your changes will be merged into the origin, and the changes in the origin into your branch. In the future, you can merge into the origin again. If your branch is protected, this is the only available option.
    • Archive branch automatically after merge - Select this option if you have finished working in a branch after the merge. Your changes will be merged into the origin.
    • Archive branch manually at a later point in time - Select this option if you have finished working in a branch after the merge. Only use it to keep the branch intact for informational purposes. Although you can continue working in the branch, this is highly discouraged. The branch requires a merge from the origin before you can merge it to the origin again. Also, there is a chance that some changes made in the origin between the two merge sessions are not properly propagated to the branch.

Now, a comparison is made. Any conflicts will be identified, so you can define a solution strategy in the next step. Nothing has been modified yet, you can still return to the previous step. If you perform a reciprocal merge, the changes from the branch are merged to the origin and vice versa. Two Merge impact overviews will be available to show the impact for both the origin and the branch.

As long as a merge session is not completed, both branches will get the status 'merging' to indicate that a merge session is pending. This will be visible in both the screen Model overview and the task Switch branch. Modifications in a branch after it is set to status 'merging' may be lost when the merge is executed.

2. Resolve conflicts

menu Models > Merging > tab Active conflicts

When the merge session is started, all actions done in the branch that is being merged compared to the origin model version are analyzed. Conflicts will occur if one the following conditions applies:

  • An object has been inserted in both the origin and the branch.
  • An object has been updated in both the origin and the branch.
  • An object has been deleted in one branch and updated in the other branch.

The list shows which origin and branch objects are involved in the conflicts that have been found.

Only conflicts that require user input to resolve them are shown in the list. You must resolve all conflicts before you can execute the merge session.

Resolve simple conflicts manually

Simple merge conflicts are conflicts where you can either choose the branch version or the origin version of the change.

If a conflict requires you to combine the changes from the branch with those from the origin, you can do this in the next step.

To resolve a simple conflict:

menu Models > Merging > tab Active conflicts

  1. Select the conflict in the list. The form shows detailed information about the conflict.
  2. If necessary, compare the changes on the tab Compare: [object type]. Here, you can view what the differences are between the branch and the origin. If the origin has been changed since creating the branch, you can compare all three versions.
  3. In the form, select a Resolution for the conflict. You can choose whether to merge the changes from the branch or the origin.
    1. For conflicts of the type "Inserted in origin and branch", you can choose not only what to do with the conflict actions but also with the dependent actions.
ResolutionDescription
- Carry out the branch action, including dependent origin actions
- Carry out the origin action, including dependent branch actions
Applies dependent actions, and results in (new) conflicts if they are conflicted.
- Only carry out branch actions
- Only carry out origin actions
Only applies the dependent action of the selected branch, but not the dependent actions of the other branch.
  1. For other types of simple conflicts:
ResolutionDescription
- Only carry out the branch action
- Only carry out the origin action
Only choose what to do with the conflict action (not necessary for the dependent action). For example, when the delete action of a table is chosen, the table is no longer available, so column insert or update actions cannot be executed.

A basic explanation of the resolution is added automatically.

Once a conflict is resolved, the chosen resolution gets a green background in the list.

tip

You can resolve multiple conflicts at once with the the task Resolve conflict . These conflicts all get the same resolution.

Overview of conflicts

Resolve complex conflicts with an external tool

Complex conflicts can occur if code has been changed in both the origin and the branch version. Both versions contain part of the resolution. You can resolve these complex conflicts by combining the changes from both branches.

To resolve complex conflicts:

menu Models > Merging > tab Active conflicts

  1. Select the conflict in the list.
  2. If necessary, compare the changes on the tab Compare: [object type]. Here, you can view what the differences are between branch and origin. If the origin has been changed since creating the branch, you can compare all three versions.
  3. Execute the task Compare code compare. An external comparison tool is opened (WinMerge or KDiff3).
  4. Compare and merge changes from both the branch and origin.
  5. Save the file in the comparison tool. The merged text is transferred to the pop-up.
  6. Select OK to store the resolution in the merge session.

A conflict comparison during a merge session

Review automatic resolutions of merge conflicts

note

This step is optional. The tab Active conflicts is not shown if only automatically resolved conflicts are present.

If identical delete or update actions are detected, conflicts are created and automatically resolved. To review these automatic resolutions:

menu Models > Merging > tab Active conflicts

  1. Disable the prefilters (Hide all solved conflicts hide solved and Hide automatically resolved conflicts hide automatically resolved.
  2. Review the automatic resolutions.

3. Review merge actions

The merge actions that are to be executed are now ready for review. Depending on the complexity of the merge, you can either:

  • Review the merge impact: A general overview of the planned merge actions. Follow this step if you do not need to exclude actions (or their dependent actions) from the merge. Usually, this is the correct choice.
  • Review the delta actions: An editable overview of the generated delta actions. You can decide for each action whether you want to apply it, and whether you want to apply its dependent actions.

Review merge impact

To view all the actions that will be performed during the execution of a merge session:

menu Models > Merging > tab Merge impact

Here, the consolidated actions are displayed in a list. The column Impact shows the action type based on the choices you have made in the previous steps:

  • insert Insert - This record only exists in the source branch and will be added to the target branch of the merge session.
  • update Update - This record has been edited in the source branch only, and the changes will be merged into the target branch.
  • overwrite Overwrite - This existing record in the target branch will be overwritten with the changes made in the source branch.
  • revert delete Revert delete - This record was deleted in the target branch, and will be restored.

The other columns show information about the merge impact on the object.

Review delta actions

To view all the delta actions that have been generated:

menu Models > Merging > tab Advanced

If necessary, you can select for each action whether and how it should be applied or ignored (tab Form > group Apply).

You can use the following prefilters for viewing your pending delta actions:

  • Actions with impact on the branch Actions with impact on the branch - Displays the delta actions that will affect the target branch when the merge session is executed. This provides insight into delta actions that may require additional checking to know if it is legitimate to apply them.
  • Actions that will be ignored Actions that will be ignored - Displays the delta actions that will not be applied when the merge session is executed. This may be because they are the same in the origin and branch due to manual selection. This provides insight into delta actions that may require additional checking to know if it is legitimate for them not to be applied.

4. Execute a merge session

When all conflicts have been resolved, you can execute a merge session. In this step, only the required changes will be executed:

  • Changes in the target branch ('merge into') will be reversed if they do not need to be merged according to your choice of conflict resolution (if available).
  • Then, the changes in the source branch ('merge from') will be added.

To execute the merge session:

menu Models > Merging > tab Merging

  1. Execute the task Execute merge session to perform the actual merge. Or: execute the task Schedule execute merge session Schedule.

    This can be useful, for example, if you want to merge outside working hours.

  2. Once a branch is merged into its origin, it will be deactivated after the merge. If you wish to continue working in that branch, clear the checkbox Deactivate branch.

After the merge, the target branch is updated according to the conflict resolution you selected.

Execute merge session

Include data migration mappings during merge

When merging a source branch into a target branch, the mappings from the source branch, along with all the intermediate mappings up to the current state of the source branch, will be combined and applied to the new model version created in the target branch after the merge.

Here is how it works:

  • When merging an origin branch (like DEVELOP) into a target branch (like FEATURE), any mappings made in the origin branch since creating the target will also apply to the target branch.
  • When merging a branch (like FEATURE) back into its origin (like DEVELOP), any mappings made in the branch since it branched from the origin will also apply to the origin branch.

This ensures that the mappings done in the branch will be re-applied when configuring an upgrade in the origin and vice versa.

note

You may need to use the task Re-apply intermediate mappings to see the effect when configuring the database upgrade of the target branch after the merge. See also Re-apply intermediate mappings.

Suppose there are mappings from upgrades of model versions done outside of the source branch (for example, upgrading from MAIN to your FEATURE branch, even though FEATURE was branched from DEVELOP). In that case, those mappings will also be copied to be applied to the target branch of the merge session (in this case, from MAIN to DEVELOP).

Cancel a merge session

During a merge session, you might want to cancel the process, for example, to make more adjustments in the branch before proceeding. In that case, you can delete the merge session. The source and target branch will no longer have the status merging, and will be exactly as they were before you started the merge session. Your conflict resolutions will not be saved.

To cancel a merge session:

menu Models > Merging > tab Merging

  1. Select the merging session in the list.
  2. Select cross and confirm that you want to delete the merging session. Any pending changes will be canceled and no changes will be made to the branch or origin.

Undo a merge session

See chapter Revert a branch in the Models and branches manual.

Was this page helpful?