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.
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.
- 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 'Merge direction' radio buttons specify the direction of the merge, i.e., which model is the source of changes and to which model the changes can be applied. These radio buttons have an impact on the 'Modifiable' check boxes. If 'Any' is chosen, then the comparison is represented in a symmetric way and both models can be modified. While 'Any' uses arrow decorators to indicate merge direction, 'Left to right' and "Right to left' uses git like decorators instead.
- The 'Comparison method' combo box allows selecting the way models are compared. A default, configurable comparison method that is suitable, e.g., for version control is available. Other methods can be added via extensions of 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 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.
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.
- 'Diff/merge between different versions of the same model': Use this configuration for a classic diff/merge between different versions of the same model. It assumes every model element has a unique identifier, either through a dedicated property or through persistence (for example, XML or XMI IDs).
- 'Transfer of elements between models created independently': Use this configuration if you need to transfer elements between models that are historically unrelated but structured in a similar way.
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.
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.
- Absolute criteria consider each model element independently of the others. A model element will always be matched in the same way if it does not change even though everything else in the model changes.
- Relative criteria, conversely, consider model elements in the context of others.
Tool tips are available for all criterion categories and all criteria. Hover over the corresponding User Interface element to see the tool tip.
- Technical IDs: The technical ID of an element is an identifier that is solely defined for persistence purposes. It is sometimes called 'extrinsic' because it does not belong to the element: it depends on the way the model is persisted and it can change when the persistence technology changes. By default, models are persisted as XML or XMI files so model elements have an XML ID. Models stored in a database through the CDO technology have a CDO ID.
- Property IDs: A property ID is an ID that belongs to the element through a dedicated property. It normally remains the same throughout the whole life of the element, which makes it the most appropriate criterion in version control contexts. Most of the time, it is the value of an attribute of type string, typically named 'id', that is randomly generated when the element is created. Note that model elements may have a technical ID and a property ID at the same time, which may (but do not have to) be the same.
- Names: If an element has a name and all its container elements also have a name, then the element has a qualified name which is the sequence of all these names. This criterion matches two elements if they have the same qualified name. It only makes sense if elements have names and naming rules forbid two elements within the same container to have the same name. The weakness of this criterion is that it is sensitive to moves: moving an element means changing its container, which generally means changing the qualified name.
- 'Use labels as names': This option allows using the label that elements have in editors as a name, even though they do not actually have a name. This criterion only makes sense if different elements have different labels.
- Structure: Two elements structurally match if they are at the same "location" in the model and if there is no other element at the same "location" that can also match. The sub-options refine the meaning of "location".
- 'Match unique roots': An element can be located at the top level of a model, in which case it is called a root. This option allows matching two elements which are both root and cannot be confused with other roots, typically because they are the only ones of their type.
- 'Match unique children': Match elements that have the same container and play the same discriminating role within it. For example, consider a modeling language that represents data, where data values can be defined as Binary Expressions that have one left operand and one right operand. Left operand and right operand are discriminating roles in the sense that only one element can play each of these roles. So if two Binary Expressions match, then their left operands will match and their right operands will match, provided they are of the same type.
- 'Match unambiguous children': Match elements that have the same container and cannot be confused with other elements within the container. Typically, elements that play the same role within the container and that are the only ones of their type to play that role. This is a more permissive criterion than the one above.
- 'Match unique roots': An element can be located at the top level of a model, in which case it is called a root. This option allows matching two elements which are both root and cannot be confused with other roots, typically because they are the only ones of their type.
- Semantics: Semantic matching encompasses criteria that are based on the knowledge of specific modeling languages. The general rationale is to try and match elements according to their nature and their meaning.
- 'Match default model contents': When a new model is being created, it may be automatically filled with default model elements. Match these default elements if present. It may only work if the top-level elements of the models match (see 'Structure - Match unambiguous roots').
- 'Match equivalent technical elements' (hidden by default, may appear in specific modeling tools): Certain modeling languages define elements that are purely technical and usually invisible to users. Match such elements according to the semantics they carry, if applicable.
- 'Diagrams: Match shapes according to represented elements: Match graphical shapes in (GMF or Sirius) diagrams if they represent the same element in the same diagram. Beware that it only makes sense if an element cannot be represented by different shapes in the same diagram.
- 'Diagrams: Match remaining shapes according to type': Certain shapes in (GMF or Sirius) diagrams may be purely technical and may not represent an element: they only make sense in the context of other more significant shapes. Match these shapes according to their type and to more significant shapes.
- 'Match default model contents': When a new model is being created, it may be automatically filled with default model elements. Match these default elements if present. It may only work if the top-level elements of the models match (see 'Structure - Match unambiguous roots').
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.
The advanced Differencing tab provides options that determine what differences are detected. By default, the following options are available.
- Ignore orders disables the detection of ordering differences, which has the advantage of increasing performance. If selected, then for example the fact that a UML class contains attributes A then B in a model and attributes B then A in the other model will yield no difference. Beware that this option prevents models whose semantics highly relies on orders from being consistently merged, e.g., UML or Sirius Sequence Diagrams. Do not select this option in such a situation.
- Keep match keys activates tool tips that display the match keys used to match model elements in the comparison editor, as shown in the snapshot below. Two model elements match if and only if they have the same match key, which is generated for each model element according to the selected matching options. Looking at the match keys allows for a better understanding of how elements have been matched, at the price of a higher memory consumption. If a match key has been obtained through relative criteria, then it is composed of several parts that are prefixed according to their origin: by default, '::' means identification by name, '@' by structure, and '~' by semantics.
- Use cache is a technical option that determines whether a cache is used for matching elements. It speeds up the matching phase if relative matching criteria are being used and enough memory is available. It is advised to not use this option if memory is limited.
Once the 'Finish' button has been clicked in the setup dialog, a few additional information dialogs may pop up.
- An 'ambiguous mapping' warning message (figure below). This message pops up if at least one of the models being compared contains duplicate match keys. If the default comparison method has been used with its default configuration, seeing this message means that each of the duplicates that appears in the dialog is an identifier that several elements of the same model have in common. The model is thus not correct and violates elementary validation rules; consequently, there is no guarantee that the comparison is correct or that merge operations will behave consistently. If, conversely, advanced matching criteria have been used, then it means they are not applicable to the selected model(s)
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).
- A 'no undo/redo' warning message (figure below). This message pops up when a comparison is being made on Sirius *.AIRD files that are already open. The strategy of the tool is to try and minimize the memory usage by comparing the models in memory. This is also true if only one of the *.AIRD files is open: the comparison will operate on the model in memory. In the case of two open models, however, undo/redo cannot be enabled at this time for technical reasons. 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.
- A progress dialog (figure below). Computing the differences between models takes some time depending on the size of the models and the number of differences between them. Click the 'Run in background' button in order to keep using your environment while the differences are being computed in parallel. If differences are found, this phase ends with the opening of a comparison editor described in the next section.
- A 'no differences' message dialog (figure below). This message dialog states that no difference has been found. The comparison process ends and no additional information is provided. This situation is different from the one where differences have been found but are considered too technical to be visible by default. In that case, a comparison editor opens with an empty Synthesis section and the technical differences can be shown using the Difference Categories dialog (see below).
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.
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.
Elements that directly carry differences, either in their properties or because they have no match, are in bold. The elements in their hierarchy are in italics unless they directly carry differences.
When hovering on the top of either of the 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).
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.
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.
This section contains a textual filter at the top of the viewer, which can be used to keep all elements whose label matches the text. The filter isn't computed while the user types the text to search, but is only computed once 'Enter' is pressed.
The buttons in the Synthesis section are respectively meant to:
Fast navigation to the next element that has differences. 
Fast navigation to the previous element that has differences.
Expand the tree of the Synthesis section. Be careful that this operation may take time on large models.
Collapse the tree of the Synthesis section.
Open the 'Difference Categories' dialog that provides Filter and Focus capabilities (see below).
- 'Update...': show the setup dialog to restart the comparison, possibly with different settings, without reloading the models. All changes made to the models are preserved. This is useful for example to iteratively tune the configuration of the comparison.
- 'Show all elements': when disabled, the Synthesis section only represents elements the contain differences, directly or via their children. When enabled, all elements from the left and right models are represented.
- 'Difference categories...': similarly to the button described above, open the 'Categories' dialog that provides filter and focus capabilities (see below).
- 'Link views': this menu item has two sub-items. 'Left/right models and synthesis' enables/disables the synchronization between the Synthesis section and the middle and right sections. 'Outside views' enables/disables the synchronization between the whole diff/merge UI and other Eclipse views such as the Properties view.
- 'Sort alphabetically': sort the elements of the Synthesis section alphabetically.
- 'Use enhanced icons': whether the icons of elements are decorated with arrows indicating the origin of the differences.
- 'Use enhanced labels': similarly, whether the name of elements is enriched with characters indicating the origin of the differences.
- 'Show left/right contents': whether the right and left models are shown in the upper area. Hiding them can be convenient if the horizontal space is limited.
- 'Show difference numbers': whether the number of differences contained by each element is displayed as a suffix of its name.
- 'Show merge impact': whether a 'merge impact' dialog must be displayed before a merge is being performed. This dialog represents all the changes that are going to be made to the model due to the merge (see snapshot below). It allows the user to better understand the consequences of his merge actions and if needed to cancel them. Those consequences are not always trivial: in order to be merged, certain differences require others to be merged at the same time in order to preserve the integrity of the model - which is done automatically by the diff/merge tool. Those differences appear as 'Implied changes' in the dialog. Note that in 3-way comparisons, merging a difference may prevent the merge of another difference in the opposite direction - which is called a conflict. Such conflicts are highlighted by a red overlay icon in the dialog.
- 'Support undo/redo': when active, the user has the possibility to undo/redo his actions via the usual shortcuts Ctrl-Z and Ctrl-Y or via the 'Edit' menu. This feature is more appropriate when the models have a limited size; otherwise, undoing a merge on a large model may be a long-running operation.
- 'Log changes to models': when active, all modifications made to the models are logged in an HTML file. This file is named 'ModelComparisonLog.htm' and is at the same location as the usual '.log' file in the '.metadata' sub-folder of the current workspace folder. If the current workspace folder is unknown, right-click a project that has been created from scratch, click the 'Properties' menu item and look for the 'Location' line in the 'Resource' category.
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.
The 
button or the 'Filters and Customization...' 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 'Filters and Customization' dialog provides control over difference categories.
Different modes are applicable to each difference category via check boxes.
- Normal: Make elements and differences of the category visible, unless a focus is set on any other category.
- Filtered: Filter out elements and differences of the category. This mode has priority over the others: if a difference belongs to several categories and one of them is in filtered mode, the difference is still filtered out.
- Focus: Only show elements and differences that belong to the category. If several categories are in focus mode, then only show elements and differences that belong to any of these categories.
Additionally, four buttons are proposed in the dialog.
- 'Apply': Apply the modes that have been set and update the whole GUI without closing the dialog.
- 'OK': Apply the modes that have been set, update the whole GUI and close the dialog.
- 'Reset': Set all categories to their default mode, which may vary according to the category.
- 'Cancel': Keep the modes that are currently applied, dismiss all changes made since the last application and close the dialog.
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.
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 (left column) that represents the properties themselves and two Value sections (middle and right columns) that represent the values of the selected property in the model that corresponds to the column.
A click on the triangle-shaped button in the Property section brings a few options.
- 'Show values on differences': when selected, only the values which are different are displayed in the Value sections.
- 'Show all values': when selected, all the values of the current attribute or reference are shown in the Value sections. Those that are different are highlighted.
- 'Show all values and properties': when selected, all the properties (attributes and references) of the current element are shown in the Details section. The properties that have differences are highlighted as in the snapshot below. It is thus possible to see all properties of a model element, although it is generally advised to use the Contextual Explorer of Modeling Amalgam view instead.
- 'Use technical representation': when selected, properties are displayed in a technical form that provides harder to read but more accurate naming, and typing information.
The purpose of the difference handling buttons is to decide what to do with differences, that is, how the compared models are being merged.
The 'Open in dedicated editor' button is enabled for textual properties only. It opens an editor that is dedicated to fine-grained textual merge (this can also be achieved by double-clicking the text in the Value sections). When the OK button of this editor is pushed, the changes done by the user are marked as accepted. If needed, they can be refined later by un-filtering the 'Ignored differences' category (see corresponding subsection above).
In a three-way comparison, the text of the ancestor can also be shown thanks to the 'Show Ancestor Pane' button (leftmost one in the tool bar).
Textual properties set apart, the general-purpose buttons for difference handling are visible in the Value sections.
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.
The 'Apply to the right/left' buttons: given an element or a value which is present in one model and not in the other, clicking this button copies the element or value and stores it in the model where it is missing.
The 'Delete on the left/right' buttons: given an element or value which is present in one model and not in the other, clicking this button deletes the element or value in the model where it is present.
The 'Ignore on the left/right' buttons: the selected differences are ignored and will not appear any longer although they are not merged. By clicking this button, the user states that the selected differences are not interesting or relevant. To make them visible again, the ignore action can be undone using the usual Undo mechanism, or the visibility of all ignored differences can be temporarily restored via the 'Difference Categories' dialog.
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.
- The 'Include differences in children' check-box determines whether the differences in the selected elements and all their children in the containment tree must be merged. Otherwise, only the differences in the selected elements are merged.
- The 'Incremental mode', when active, does not delete elements or values. Only the differences that preserve the existing data are merged.
- 'Show merge impact' overrides the 'Show merge impact' option (see description of the corresponding menu item of the Synthesis section), which is particularly useful to avoid showing large impacts when a large number of differences are selected.
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:
This section summarizes the essential steps that must be followed to deal with model differences.
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.
The following buttons can be used to resolve differences.
Buttons for navigating between differences.
Buttons for merging and ignoring differences.
or the Ctrl-S shortcut for saving the changes.
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.
When using Diffmerge within a Sirius application, description on elements or diagram elements may refer to some external images. Note that when the user will merge some references toward images, please make sure that those images are also available by the destination model, otherwise images will not be loaded properly.
In the case of Sirius applications, when the target resource does not have the session opened external image dependencies will not be added to it, which may lead to various issues. In order to work around this, it's recommended to either have the session opened on the target of the Diffmerge or, after the process is finished, to update the external dependencies of the target resource. See more regarding that at the last bullet point of Changes in Sirius 7.1.0 - User-visible changes.
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 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, 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
- Installing the VCS client in Eclipse.
- Installing the EMF Diff/Merge plug-in for this client (at this time, only EGit).
- Declaring the file extension of the models as XMI: Window - Preferences - General - Content Types - Text - XML - XMI Metadata Interchange - Add: type, for example, '*.myfileextension'.