User's Guide

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. The GUI supports setting up and configuring comparisons, visualizing differences and selectively merging those differences.

Other technological usages of EMF Diff/Merge as well as complementary technical documentation are available online on the EMF Diff/Merge wiki.


Starting the Diff/Merge GUI

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 setup dialog involving the selected files is shown.

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


Configuring a Comparison

The 'Configure...' button in the setup dialog makes it possible to change the way a comparison is computed: how elements are being matched, what differences are detected and how they can be merged, what extra information is provided.


Predefined Configurations

With the default comparison method, the configuration dialog looks like the one below.

The radio buttons correspond to predefined configurations that reflect common use cases.

Additional configurations may be available in specific modeling tools.

If the needs are not covered by these predefined configurations, it is possible for an advanced user to switch to the advanced configuration mode by clicking the 'Show advanced settings' button. Additional tabs become visible as in the figure below.

The subsections below describe the options that are provided by default. However, additional options may be available in specific modeling tools.


Advanced Matching

The advanced 'Matching' tab provides options that determine the way elements are matched. By default, the following options are available.

Matching criteria fall into two categories.

Criteria are listed in increasing order of priority. For example, when 'Names' and 'Property IDs' are enabled, if an element has a qualified name then its property ID is ignored. It will only be matched to an element in the other model if that element has the same qualified name.

Tool tips are available for all criterion categories and all criteria. Hover over the corresponding User Interface element to see the tool tip.

Applicability

Beware that relative criteria (names, structure, semantics) are more expensive to compute than absolute criteria: they require more computation time and more memory. If enough memory is available, the 'Use cache' option from the Misc tab (see below) allows the computation of the comparison to be done faster.

Note that all matching criteria are not applicable to all models. Names, for example, only work if every model element has a unique (qualified) name. If, on the contrary, there is name duplication in the model (or, for structural/semantic criteria, structural/semantic ambiguities), then the diff/merge tool will detect that the comparison is inconsistent and will report it as described in section 'Computing a comparison'.

In such a situation, the 'Keep match keys' option from the Misc tab (see below) can be useful to understand why there are matching inconsistencies. According to this analysis, the user may decide to either modify the models to avoid inconsistencies, for example by enforcing name uniqueness constraints, or use the 'Update' feature provided by the comparison editor to experiment with slightly different matching criteria.


Other Advanced Options

The advanced Differencing tab provides options that determine what differences are detected. By default, the following options are available.

The advanced Misc tab provides miscellaneous additional options. By default, the following options are available.


Computing a Comparison

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

Warning: Do not start a merge activity if this message appears; fix the model(s) or the comparison configuration first (see the discussion on advanced matching applicability above). 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 action stores the list of duplicate IDs in the clipboard of the operating system for later analysis. 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 hidden (red circle in figure below).




Exploiting a Comparison

The comparison editor presents the differences which have been computed.

The editor is composed of two horizontal areas intersecting with three vertical areas or columns.


Vertical Areas

The middle column represents the contents of the left model while the right column represents the contents of the right model. Each side is associated to a color: by default, dark red for the left model and blue for the right model. This color code is also used in other dialogs of the diff/merge tool in order to prevent any ambiguity.

When hovering on the top of any of these columns, the complete path to the model is displayed as a tool tip if the window is too narrow.

A lock toggle button is visible at the top of these columns. When selected, modifications to the corresponding model are forbidden. Consequently, the merge buttons which are usually enabled will be disabled if they mean to modify the model. Use this mechanism to temporarily protect a model against accidental modifications.

The upper section of the left column is the Synthesis section. It focuses on the parts of the models that actually contain differences.

The three columns are synchronized: clicking an element in the Synthesis section highlights it in the other sections and vice-versa (unless the 'Link views' option is disabled, see below).


Horizontal Areas

The two horizontal areas correspond to two different levels of detail. The upper area focuses on which model elements are present and where. The lower area is the Details section: it shows the properties (attributes and references) of the model element that is selected in the upper area.

For example, if a modified element (in purple) is being clicked in the Synthesis section (upper area), then the Details section (lower area) displays all the properties of the 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. For instance, in the snapshot above, element 'In-Flight Entertainment System' is selected in the Synthesis section; the Details section shows that it has a difference on its name: the name is 'In-Flight Entertainment System' in the left model and 'P1' in the right model.


Synthesis Section

The Synthesis section represents the differences between models in terms of additions, deletions and moves of elements. According to the color 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 properties (attributes or references) are written in purple. The number of differences they contain is written between parentheses (unless the 'Show difference numbers' option is disabled, see below).

The location of an element, with respect to the model tree, is considered as a property of the element named 'Container'. A difference on this property can be interpreted as a move. If an element is at a different location in the left and right models, it is represented in the Synthesis section at the same location as in the left model.

The buttons in the Synthesis section are respectively meant to:

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

Important notice: the last three 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.


Difference Categories Dialog

The button or the 'Difference categories...' menu item allow 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. The 'Difference Categories' dialog provides control over difference categories.

Different modes are applicable to each difference category via check boxes.

Hover the mouse pointer over a category to see its description in a tool tip.

Additionally, four buttons are proposed in the dialog.

Note that the 'Difference Categories' dialog is not modal, so differences can be navigated while the dialog is open.

If there are chances that differences that are visible with default settings are filtered out due to the selected category modes, the '[filtered]' mention appears in the header of the Synthesis section (figure below). It is a warning that even though the GUI may not show any difference, the work for difference resolution may not be finished. Just click the 'Reset' button then the 'OK' or 'Apply' button to make remaining differences visible.


Details Section

The properties of the element selected in the Synthesis section are visible in the Details section (lower area). This section is subdivided into a Property section that represents the properties themselves and two Value sections that represent the values of the selected property in the model that corresponds to their column.

A click on the triangle-shaped button in the Property section brings a few options.


Difference Handling Buttons

The buttons below are shown in the lower area near the Value sections. Their purpose is to decide what to do with differences.

In other words, those buttons control how the compared models are being merged. They are grouped into two 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 selected, 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 useful 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:


Difference Resolution in a Nutshell

This section summarizes the essential steps that must be followed to deal with model differences.

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.

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 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 ('[filtered]' 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 considered by the user and either merged or explicitly ignored or filtered out.


Integration with 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

Version Control Systems

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 well-identified versions, commits or branches, understand the content of a commit, or resolve conflicts when merging branches.

This can be achieved by

If this setup is successful, VCS-based features, for example those available through the 'Compare with...' contextual menu, will automatically use the EMF Diff/Merge GUI when appropriate. In the case of EGit, be careful to not directly use content that is pre-merged by Git (see Window - Preferences - Team - Git, 'Merge tool content': do not select 'Workspace').