Basic Usage

Overview

EMF Diff/Merge is a diff/merge technology for models. Its main purpose is to help build higher-level tools that need to merge models based on consistency rules. Typical usages include model refactoring, iterative model transformations, bridges between models or modeling tools, collaborative modeling environments, or integration with Version Control Systems.

A GUI is also provided for a classical usage within Eclipse. This document explains how users can use the GUI to compare and merge models manually.

Other technological usages of EMF Diff/Merge as well as a more general documentation are available online on the EMF Diff/Merge wiki.


Opening the Diff/Merge GUI

The EMF Diff/Merge GUI supports setting up comparisons, visualizing differences and selectively merging (acceptance/refusal) those differences.

The GUI is accessible via the 'Compare With' - 'Each Other as models' popup menu item. This menu item is enabled when two model files are selected in the Project Explorer as illustrated in the figure below.

It can also be used on model-based diagrams (GMF files, or Sirius *.aird files for example) or model fragments.

Whenever the menu item is clicked, a comparison setup dialog involving the selected files is shown.

The 'up-and-down-arrows' button on the right can be used to swap the position of models - left or right - in the tool, for convenience.

The 'Modifiable' check boxes allow defining which model(s) can be modified. If a check box is unselected, it will not be possible to carry out merge actions which would modify the corresponding model. This is a way to protect a model against accidental changes due to a wrong usage of the tool.

The 'Reference' radio buttons specify which model should be considered as the reference model, that is, the model of which the other model is an evolution. This does not alter the way models are compared, only the way differences are represented. Setting a value which is not 'None' is equivalent to running a three-way comparison (see below) where the ancestor is the model on the selected side. More precisely:

The 'Comparison method' combo box allows selecting the way models are compared. By default, only the standard method for version control is available. Other methods can be added via add-ons to the diff/merge tool.

If the user selects three files, the comparison proposes to compare two files taking into account a third common ancestor as illustrated below.

The 'Configure...' button makes it possible to alter the result of the comparison. When clicked, if the selected comparison method does not provide advanced configuration settings, then the resulting dialog looks like the one below.


Note that two model elements match if and only if they have the same 'match ID', which by default refers to their ID property visible in the Properties view.


Warning: This option prevents models that highly rely on orders from being consistently merged, e.g., UML or Sirius Sequence Diagrams. Do not select this option in such a situation.


Once the 'Finish' button has been clicked, a few additional information dialogs may pop up.

Warning: Do not start a merge activity if this message appears; fix the model(s) first. For that purpose, it may be helpful to select the duplicate IDs in the dialog, right-click, then select a 'Copy to clipboard' menu item. This stores the list of duplicate IDs in the clipboard of the operating system.

The 'ambiguous mapping' message can be shown again at any time after the comparison has been displayed. It is accessible via the 'Show inconsistencies' button which is otherwise disabled (red circle in figure below).


As indicated in the message, if the purpose of the comparison is to merge models, not just to compare them, and undo/redo is required, then it is necessary to close at least one of the models before starting the diff/merge tool to regain the undo/redo capability.


Features of the GUI

Main interface

When started, the diff/merge tool displays a progress dialog. Computing the differences between models takes time according to the size of the models and the number of differences between them. Click the 'Run in background' button in order to keep working with Eclipse while the differences are being computed in parallel.

This phase ends with the opening of an editor. The editor presents the differences which have been computed.

The editor is composed of 2 horizontal sections and 3 vertical sections.

Vertical sections

The middle section represents the contents of the left model while the section on the right-hand side represents the contents of the right model. When hovering on the top of any section, the complete path to the model is displayed as a tooltip if the window is too narrow.

In addition, each side is associated to a colour: by default, dark red for the left model and blue for the right model. This colour code is also used in other dialogs of the diff/merge tool in order to prevent any ambiguity.

The section on the left-hand side is the Synthesis section: it represents the differences between the models. According to the colour code, model elements which are present in the right model but not in the left model are written in blue, while they are written in dark red in the opposite case. Elements which are present in both sides but have differences in their attributes or references ('modified elements') are written in purple. The number of differences they contain is written between parentheses. The 3 sections are synchronised: clicking an element in the Synthesis section highlights it in the other sections and vice-versa.

Horizontal sections

The 2 horizontal sections correspond to 2 levels of detail. The top section focuses on model elements and only reflects that level of granularity. The bottom section is the Details section: it shows the contents (attributes and references) of the model element which is currently selected in the top section.

For example, if a modified element (in purple) is being clicked in the Synthesis section, then the Details section displays all the attributes and references of that element that have differences. The corresponding values are displayed in the middle and right parts of the Details section according to the model they belong to. These sub-sections are called the Value sections. For instance, in the snapshot above, element 'N2' is selected in the Synthesis section; the Details section shows that it has a difference on its name: the name is 'N2' in the left model and 'Niveau 2' in the right model as shown in the Value sections.

Locking models

The lock button prevents any modification to the corresponding model. Consequently, the merge buttons which are usually enabled will be disabled if they involve a modification in that model.

Differences navigation

These buttons are respectively meant to:

Additional features are available via a click on the triangle-shaped button.

Important notice: the last 3 features ('show merge impact', 'support undo/redo', 'log changes to models') have a cost in performance. Merging differences typically takes longer and requires more memory if they are enabled. It may thus be relevant to disable them when performing large merges. Note that undo/redo is the most expensive feature and logging the least expensive.

Filter and Focus capabilities

The button allows filtering out the displayed differences in order to ease their understanding and split the merge activity into successive phases that focus on different kinds of differences.

A difference category covers a subset of the differences or model elements in a comparison. Conversely, a given difference or element can belong to several categories. Different modes are applicable to difference categories.

Dealing with differences

Features are available via a click on the triangle-shaped button.

Those buttons control how the compared models are being merged. They are grouped into 2 symmetrical groups, one group for each model. The buttons in the groups are automatically enabled and disabled according to the current selection.

These buttons can be applied on values when the current selection is in a Value section, or on elements when the current selection is in the Synthesis section. If the selection is multiple or contains several differences, the 'Delete' buttons are disabled and the 'Copy' buttons allow merging all the differences. Clicking them pops up a dialog which allows the user to state how differences must be merged.

Similarly to the 'Copy' buttons, the 'Ignore' buttons may trigger a dedicated dialog which allows controlling whether the action is applicable to all children of the selected elements. If the check-box is not ticked, differences on the selected elements are ignored but not differences on their children.

Textual comparison

While the recommended comparison method for model and diagram files is using the Diff/Merge tool, it may sometimes be necessary to compare model and diagram files textually. This is possible by selecting the two model or diagram files and choosing 'Compare With' - 'Each Other' in the Project Explorer popup menu. This will open the Diff/Merge comparison, with the difference that it is possible to switch to a textual comparison by selecting "Text Compare" in the comparison editor drop-down menu:


Merge process in a nutshell

Opening the GUI

The EMF Diff/Merge GUI can be opened in Eclipse using the 'Compare With' - 'Each Other as models' contextual menu on files of the workspace.

Resolving differences

The following buttons can be used to resolve differences.

The precise meaning and usage of each of them is described in the previous section.

Note that in some cases, performing a merge can take time especially if it is a global merge between large models. A progress bar is being displayed during the operation.

Saving merge decisions

Resolution of differences is considered to be finished when the content of the Synthesis section is empty, no significant difference is filtered out (the '[filtered]' mention does not appear in the header of the Synthesis section) and changes have been saved by pressing Ctrl-S.

Note that the absence of visible differences does not mean that the left and right models are identical. It simply means that all differences have been checked by the user and either merged or explicitly ignored.


Version Control

Local File History

Eclipse maintains a local history of file modifications and allows to compare a file with a version from local history. For more information refer to the local history documentation

Eclipse Team

Eclipse provides mechanisms (Eclipse Team) that make interactions with Version Control Systems (VCSs) easier. VCS clients that integrate within Eclipse and use these mechanisms, for example EGit for Git or Subversive for SVN, can interact with EMF Diff/Merge in order to, e.g., compare versions, understand the content of a commit, or resolve conflicts when merging branches.

This can be achieved by

If this setup is successful, features that are available through sub-menus of the 'Compare with...' contextual menu should use the EMF Diff/Merge GUI.