MPatch Tutorial

Quick overview of what you learn in the tutorial:

The contents of this tutorial is also shown in the (outdated) screencasts; please note that the screencasts use the old term model-independent differences instead of MPatch.


The tutorial uses a shipped example for illustrations. To import it into your workspace, select Window -> Show View -> Other... -> Plug-ins, and look for the plugin org.eclipse.emf.compare.mpatch.example. Right click it and select Import As -> Source Project.

Import example

You should now have a project available in your workspace containing the following files:

Example models

model/library.ecore - the base version of a simple library model
model/library_karl.ecore - a modified version of the base version
model/library_eve.ecore - another modified version of the base version

The .ecorediag-files are diagrams for the models. If you installed the Ecore Tools, you should be able to open these files and view the models graphically.


At the moment, MPatches are not created directly, but from existing differences created with EMF Compare. The reason is that we do not want to introduce yet another model-comparison algorithm but instead use existing solutions which are already flexible and exdendable.

To compare library.ecore and library_karl.ecore, select both files, right click and select Compare With -> Each Other. Then a model comparison dialog should open which shows both model and their differences in EMF Compare:

EMF Compare


The process of creating MPatches involves a set of optional transformations which add further features as explained below.

There are currently two ways of starting the transformations:

  1. From within the comparison dialog: Select 'Export as MPatch' (see previous screenshot).
  2. From an .emfdiff-file which was previously saved from a comparison dialog ('Export as emfdiff') by right-clicking it and selecting MPatch -> Transform emfdiff to MPatch.

In the end, a wizard for the creation of MPatches is started. Select the library folder as the parent folder and enter karls_diff.mpatch as a file name. Select the transformations 'Intuitive Grouping', 'Scope Expansion', and 'Unbound Symbolic References' on the next wizard page (their order doesn't matter), make sure the Condition-based symbolic reference creator is selected, and press Finish:

Optional transformations

The Intuitive Grouping structures the changes in groups. Unbound Symbolic References makes changes not only applicable to one single but to a set of model-elements. Scope Expansion modifies the MPatch such that the changes are applicable to slightly changed models. The condition-based symbolic reference creator produces references which are required by some of the transformations.
Please see this page for more detailed explanations.

Next you should see a summary of the transformation results and you should have a file library/karls_diffs.mpatch in your example project:

Transformation result


Now we are going to apply the just created differences to the other model.

Right-click karls_diff.mpatch and select MPatch -> Apply MPatch. This opens the wizard for MPatch application:

  1. Selection of MPatch
    Select MPatch for application

  2. Selection of the model to which the MPatch should be applied;
    please select model/library_eve.ecore from the workspace here.
    Select target model

  3. Resolution of symbolic references;
    this page is the most important for MPatch application--in order to effectively use MPatches, you need to understand what happens here:
    It defines to which model elements (the model was choosen in the previous step) each individual change should be applied.
    The symbols have the following meaning:
    -- The number of resolved model elements does not match the required number
    -- The change is not applicable to the set of selected model elements
    -- Resolution is ok, the change can be applied.
    The number of resolved model elements can be changed by clicking the button [...] in the table cell which shows the resolved model elements.
    Resolve symbolic references
    Note that a change can be applied to multiple model elements at once because if the 'Unbound Symbolic References' transformation was performed!
    Note also that the user can make a selection by ticking (thus ignoring) changes, which is already done for the unknown changes.

  4. Storing an intermediate emfdiff (optional);
    If the intermediate models should be saved after the application process (ticking Store intermediate models in step 3), then the wizards asks for a place to store the emfdiff file.

  5. Storing an intermediate model (optional);
    If the intermediate models should be saved, the wizards asks for a place to store a copy of the model selected in step 2.

  6. Review all settings;
    When clicking Finish, a message confirms the application of the four changes. If Review result with EMF Compare is ticked, then a comparison of the unchanged and the changed model is opened afterwards.
    Review all settings
    Review all settings

  7. Review result with EMF Compare (optional);
    EMF Compare opens and shows all applied changes in a comparison view. Please note that due to a bug (or feature?!) in EMF Compare, any changes in this view are discarded if the intermediate models are not saved.Review all settings
    Now we can see:

Now you know the basic steps to use MPatches.