Using the bundled Eclipse marketplace client you can install EMF Compare in one click. Just type "emf compare", click on search, and then on install.
EMF has been part of the Eclipse release train since Galileo, you can install it using the following update sites, depending on your platform. Note that the following are not meant to be visited in your internet browser; they must be pasted in the Help > Install New Software dialog of your Eclipse, as p2 repositories.
http://download.eclipse.org/releases/mars http://download.eclipse.org/releases/luna http://download.eclipse.org/releases/kepler http://download.eclipse.org/releases/juno http://download.eclipse.org/releases/indigo http://download.eclipse.org/releases/helios http://download.eclipse.org/releases/galileo
The Download page lists more specific update sites if you wish to try one of the latest integration builds.
Please note that the EMF Compare development team does its best to maintain downward compatibility towards Helios (Eclipse 3.6). Following is the compatibility chart :
| EMF Compare | Eclipse 4.5 - EMF 2.11 | Eclipse 4.4 - EMF 2.10 | Eclipse 4.3 - EMF 2.9 | Eclipse 4.2 - EMF 2.8 | Eclipse 3.8 - EMF 2.8 | Eclipse 3.7 - EMF 2.7 | Eclipse 3.6 - EMF 2.6 | Eclipse 3.5 - EMF 2.5 | Eclipse 3.4 - EMF 2.4 | Eclipse 3.3 - EMF 2.3 | Eclipse 3.2 - EMF 2.2 |
|---|---|---|---|---|---|---|---|---|---|---|---|
| 3.1 | |||||||||||
| 3.0 | |||||||||||
| 2.1 | |||||||||||
| 2.0 | |||||||||||
| 1.3 | |||||||||||
| 1.2 | |||||||||||
| 1.1 | |||||||||||
| 1.0 |
An empty cell indicates that the compatibility hasn't been tested for a particular combination.
The main points of interest are highlighted in the following picture :
The toolbar displays the current status of the comparison and allows you to act on differences.
When you compare models with one in a read-only mode, some of actions proposed by the toolbar are slightly different. Indeed, if you compare a model with the local history, or you compare a model with a remote model stored in a repository (e.g. via EGit), the latter is in a read-only mode. You will not able to merge differences to this read-only model. You will only accept or reject changes for your local model.
In the area that shows the overview of differences, you also can perform merge actions using the contextual menu (i.e., right-click an item in the tree). These actions correspond to those in the toolbar.
If you do a right-click on a difference in the viewer, a contextual menu offers you to merge the selected difference.
If you do a right-click on a model element or a resource, you can merge all contained non-conflicting differences with one click.
When you run a comparison involving two models (a 2-way comparison), the icons associated with differences are:
represent an addition in the left side model of the comparison.
represent a deletion in the left side model of the comparison.
represent a change (set/unset/move) in the left side model of the comparison.
When you run a comparison involving three models (a 3-way comparison), the icons associated with differences are:
incoming differences are changes that were made in the right-side/remote model since common ancestor.
outgoing differences are changes that were made in the left-side/local model since common ancestor.
represent an incoming addition difference.
represent an incoming deletion difference.
represent an outgoing addition difference.
represent an outgoing deletion difference.
incoming conflict differences are changes that were made in the right-side/remote model since common ancestor, and are in conflict with the left-side/local model.
outgoing conflict differences are changes that were made in the right-side/remote model since common ancestor, and are in conflict with the right-side/remote model.
represent an incoming addition conflict.
represent an incoming deletion conflict.
represent an outgoing addition conflict.
represent an outgoing deletion conflict.
incoming pseudo conflict differences are changes that were made in the right-side/remote model since common ancestor, and are in pseudo conflict with the left-side/local model.
outgoing pseudo conflict differences are changes that were made in the right-side/remote model since common ancestor, and are in pseudo conflict with the right-side/remote model.
represent an incoming pseudo conflict addition.
represent an incoming pseudo conflict deletion.
represent an outgoing pseudo conflict addition.
represent an outgoing pseudo conflict deletion.
The merged differences are displayed in gray and have a distinct icon.
represent a difference that has been merged from right to left.
represent a difference that has been merged from left to right.
When you compare models with one in a read-only mode, the icons are:
represent a change that has been accepted.
represent a change that has been rejected.
The following table shows the state the model should be in after clicking on EMF Compare comparison editor toolbar's buttons:
| What it should be | Type of Difference | Ancestor Model | Left/Local Model | Right/Remote Model |
 Merge to right
|
 Merge to left
|
 Accept
|
 Reject
|
 Merge all non-conflicting left differences to right
|
 Merge all non-conflicting right differences to left
|
 Accept all
|
 Reject all
|
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 3-way |
Outgoing deletion
|
X | / | X | RIGHT = / | LEFT = X | MARK AS MERGED | LEFT = X | RIGHT = / | DO NOTHING | MARK AS MERGED | LEFT = X |
|
Incoming Deletion
|
X | X | / | RIGHT = X | LEFT = / | LEFT = / | MARK AS MERGED | DO NOTHING | LEFT = / | LEFT = / | MARK AS MERGED | |
|
Outgoing addition
|
/ | X | / | RIGHT = X | LEFT = / | MARK AS MERGED | LEFT = / | RIGHT = X | DO NOTHING | MARK AS MERGED | LEFT = / | |
|
Incoming Addition
|
/ | / | X | RIGHT = / | LEFT = X | LEFT = X | MARK AS MERGED | DO NOTHING | LEFT = X | LEFT = X | MARK AS MERGED | |
| 2-way |
Deletion
|
/ | X | RIGHT = / | LEFT = X | MARK AS MERGED | LEFT = X | RIGHT = / | LEFT = X | MARK AS MERGED | LEFT = X | |
|
Addition
|
X | / | RIGHT = X | LEFT = / | MARK AS MERGED | LEFT = / | RIGHT = X | LEFT = / | MARK AS MERGED | LEFT = / |
When a model is split into fragments, and only some of them have changes, the structure merge viewer (upper part of the comparison editor) and the content merge viewers (lower parts of the comparison editor) display the models involved in the comparison but don’t display the fragments that have no changes.
If a change (x) is detected in a fragment (B), and this fragment is a child of another fragment (A) that has no changes, then (A) won't appear in the structure merge viewer (upper part of the comparison editor) and the content merge viewers (lower parts of the comparison editor). As a result, users will think (B) is the root of the global model.
To avoid this, the idea is to display intermediate node(s) (represented as [ ... ]) in order to show to users that it exists something (fragments, i.e. a parts of models) between/above the changes.
| Before | After |
|---|---|
|
|
Once installed, you can compare your files (locally or from EGit Version Control System) as usual using the Compare With menu. See Known_Bugs_and_Limitations section to see how to benefit from EGit support.
You can compare two or three models by selecting them and then using the Compare With > Each Other menu:
If you run a 3-way comparison (with 3 models), you have to select the ancestor of the comparison:
You can also compare your local model with one of its previous version available in the local history. For that, use the Compare With > Local History menu:
The following displays the important part of a model life cycle with regards to the comparison. The full life cycle can be followed on Sample Use Case. See Known_Bugs_and_Limitations section to see how to benefit from EGit support.
For this test, we'll suppose that you are trying to use EMF Compare on UML models shared under git. This will not go in details about UML and Git. We'll assume that you know how to manipulate an UML model, create or clone a git repository, share a project under it and use standard Git operations.
The name of our sample project will be "library". It contains a single folder "model" containing two models :
The model itself is a very simple library. Graphically speaking :
We commit this initial file as the original model. We then slightly modify it so that it now looks like :
But how do we know exactly what changed? Let's compare this with the file from the Git Index :
This will open a comparison editor. Let's select one of the differences displayed on its top half :
In this case, it is possible to merge towards the right : the index version of the model is editable, like any other file in the index. If we merge this difference towards the right, then it will exist an unstaged version of the model, and a staged version of the model, that will include the merged difference.
But this comparison with index is mainly useful in order to determine exactly what changed in our version. Let's commit our changes on the master branch.
After that, our model can evolve, and evolve separately in multiple branches. Let's consider the case where we would have a master branch differing from a borrowables branch such as the two look like this (the branching point was the model we've already displayed above) :
| Master | Borrowables |
|---|---|
|
|
Before we continue working on our Borrowables branch, we'd like to retrieve all modifications that have been pushed to master. With the "Borrowables" branch checked out, we'll use the Compare With > Branch, Tag or Reference action :
and compare with master :
This shows us all differences between our local copy and the master branch that were made since the 'branching' point.
Same as previously, you can navigate through the differences via the top panel, the structural view. There are three main kind of elements displayed here.
Regular elements, that mimic the containment tree of your input models, are there to separate the various differences and let you know where they were actually detected. Then there are
incoming differences, decorated with a blue arrow (
) or a derived icon, and
outgoing differences decorated with a gray arrow (
) or a derived icon.
Incoming differences are changes that were made in the remote branch (here, master) since the branching point (common ancestor). Outgoing differences are changes that were made in the local copy (here, the borrowables branch) since the branching point.
There are no conflicts here, since UML uses computed identifiers (XMI ID) for the model elements. Thus, what looks like a conflict (the "Date" type that's been added on both branch in the types packages) is actually two distinct differences.
The interface also lets you display the common ancestor of both models through the
icon. For example, if we select the
Book class, we can see how it looks like on all three versions :
You can navigate through the differences using the appropriate actions, either the previous (
) or the next (
) difference.
The remaining two actions are those that actually interest us here we can either accept all non-conflicting differences to the local copy through
or accept them one after the other through
.
Accept all differences is not what we seek : we want to keep the changes we made locally, not revert them to the state they had before the branching point (which is their current state on master, the right side). We will then select all incoming differences (under the Right side node) one after the other and merge them one by one. This gives us our merged model :
In case of a comparison with remote models, EMF Compare will detect resource name changes. The comparison editor will allows you to accept or reject those changes. Furthermore, in case of a Papyrus diagram & model renaming (renaming all .di, .notation and .uml files), the 3 differences will be accepted or rejected together, in order to maintain the consistency of the models.
This feature allows you to group differences together in the structural view according to a set predicate. By default, EMF Compare provides four distinct grouping strategies :
New grouping strategies can be provided to EMF Compare through extension points. See Add your own group section in developer guide for further details.
This features allows you to filter differences out of the structural view according to a set predicate. By default, EMF Compare provides four distinct filters :
If you install UML support for EMF Compare, an additionnal filter will also be provided in case of a comparison invloving UML models:
All settings related to filters are explained in the Filters customization section.
New filters can be provided to EMF Compare through extension points. See Add your own filter section in developer guide for further details.
When a 3-way comparison has conflicts, all differences involved in the same conflict are grouped under a Conflict node.
In the following case, the Employee Smith has his manager reference in conflict. The left side of the comparison shows that the manager of the Employee Smith is the employee Lennon while the right side side shows that the manager is the Employee Webster. The consequences of a merge from right to left of the selected difference are displayed.
When the left side difference Employee Lennon [ manager changed ] is selected in the top panel, the right side difference Employee Webster [ manager changed ] is highlighted in red, that means if the the left side difference Employee Lennon [ manager changed ] is merged from right to left, then it will be impossible to merge the right side difference Employee Webster [ manager changed ] from left to right.
After the merge of the left side difference from right to left Employee Lennon [ manager changed ], the right side difference Employee Webster [ manager changed ] is not "mergeable" from left to right anymore, it has been merged from right to left automatically.
In case of differences made on String-typed attributes, specifics actions are available in the top-right of the content viewer panel.
PENDING UPDATE, this demo displays EMF Compare 1.3 Demo
EMF compare provides the ability to compare models with Papyrus graphical modeler (GMF Diagrams). To get the graphical comparison, the EMF Compare Papyrus integration feature and Papyrus have to be installed. Note that the developments about Papyrus integration are not finished yet: the results might be not relevant. The graphical comparison will be launched if you compare diagrams files (.di), or if you compare models that have diagrams associated in the same folder. In the same way as the semantic model comparison, the graphical model comparison uses the same color coding, to distinguish incoming and outgoing changes, and conflicts. To put in relief the graphical differences, some decorators are used:
The color of the concerned decorators are highlighted on selection of the difference.
In the following example, a 3-way comparison is run with UML class diagrams. We can see that a Shape associated to a semantic uml class named A has been added on the left side of the comparison. After selected the difference in top panel, we can see the concerned elements in down panels. In the left part, the Shape A is highlighted in gray because it is an incoming change. In the right part, a phantom is drawn at the place the Shape should be after merging from right to left.
About phantoms (place-holders):
To ease their readability, in some cases, their context have to be displayed:
They are drawn as:
Here is an example of nested phantom:
Have a look on the following demos :
PENDING update videos
Demo : Comparing Ecore files with diagrams
Demo : Comparing UML files with diagrams
EMF Compare does not act simply on the selected files, but on their whole logical model (a given model can be split through multiple files through EMF control action). Thanks to that, if you try and compare a model file that reference other model files, the comparison will still be able to take these "other" files into account. For example, if you try and compare a genmodel file (that depends on its underlying ecore file) :
EMF Compare will actually consider both files when comparing :
PENDING UPDATE Demo
A specific work has been done with EMF Compare for UML. It consists in an additional filter named UML refined elements. This filter is active by default when a comparison involves UML resources. Note that the developments about UML integration are not finished yet: the results might be not relevant.
The filter groups UML consistent differences together in one difference. For example, a UML association is modeled by an association element and several sub-elements:
If EMF Compare detects a change on an element of type association, it will group all changes on the sub-elements of the association to the association difference. The goal of this filter is to ease the merge of differences. Indeed, all you have to do is to merge the association difference and it will merge all the sub-differences with it.
Here is the comparison of two UML model, one with an association (the left side), another without (the right side). The UML refined elements filter has been deactivated:
We can see a lot of differences. The same comparison with the UML refined elements filter activated:
PENDING
Demo : Specific support to encapsulate profiles and stereotypes diffs
During each comparison EMF Compare uses several engines (see Comparison process)
EMF Compare offers a way to configure those engines.
To customize matching phase go to the "Engines" preference page.
Some of the registered Matching engines could be configured. If so, an extra panel will be displayed on the left part of the preference page when the Match engine is selected.
The matching strategy of the default match engine can be configured.
Basically, you can choose to use either a strategy based on object identifiers or a strategy based on object content or both.
Additional Match Engines can be contributed through EMF Compare's extension point (see Override Match Engine). They can be enabled or disabled from the preference page.
To customize one of the other phase, go to the "Engines" preference page.
On this tab you can select which engine will be used by the comparison process. To do so, check the engine you want to define as default.
Result of each phase of the comparison process (see Comparison process) can be refined thanks to post processors.
More information:
To customize those post-processors go to the related preference page.
On this page you will find all registered post processors. They have been sorted by ordinal (top element of the list will be executed first). To enable or disable any post processor simply check or uncheck each of them. Unchecked post processors will not be triggered during later comparisons.
For each comparison, EMF Compare needs to define which resources are about to be compared. This scope is called the logical model (see Logical Model). Model resolvers are used to define strategies to build this logical model. The model resolvers will try and find cross referenced resources starting from the compared one in order to determine the logical model that needs to be compared along with it. This can be used to widen or reduce the scope in which EMF Compare will seek these linked resources.
To customize the model resolution behavior go to the "Resolution strategy" preference page.
EMF Compare proposes different strategies:
Other external strategies might be contributed to EMF Compare. In that case it may happen that the selected strategy can not handle a comparison. If it is so, EMF Compare will use the default strategy.
EMF Compare can prevent building the logical model. In that case, it will only compare the selected resources. To disable model resolution, check the button called "Disable model resolution".
You can customize the colors used by EMF Compare to highlight differences in the user interface.
You have already been explained how to use filters to hide or display differences in EMF Compare UI (see Toolbar). This chapter teaches you how to customize filter default activation.
First open the filters preference page:
The first panel (1) is used to define which filters should be activated by default. Checked elements will be activated for later comparisons. Of course, only filters that can handle the comparison will be activated (for further explanations see Add you own filter).
The second panel (2) is used to define the synchronization behavior between the filters selection in UI and the preferences. The combobox in the preference page has 3 distinct values:
You have already been explained how to use groups to gather differences in EMF Compare UI (see Toolbar). This chapter teaches you how to customize the default activated group in EMF Compare.
First open the Groups preference page:
This page is divided in two tabs. The first tab handles 2-way comparisons and the second tab handles 3-way comparisons. Each tab contains two panels:
The top panel (1) is used to define the default group. EMF Compare uses an ordered list of groups to determine which group should be the default one. The first group in this list that can handle the comparison is chosen as default group. To change it, simply put the desired group in top of the list. To do so, use the up and down buttons located on the right side of the panel.
The bottom panel (2) is used to define a synchronization behavior between selected group in UI and the preferences. The combo box lets you choose between 3 different behaviors:
In EMF item providers are used to define how elements are displayed (label, icon etc..). They belong to the EMF.Edit framework. Item providers are generally contributed to EMF however it can happen that some of them are directly contributed to EMF Compare. In general, it's done if you want to customize the way elements are displayed in EMF Compare without impacting other editors. If you go to the preferences of EMF Compare you will find a page named "Item providers".
In this page, you will find all item providers that have been directly contributed to EMF Compare. Some elements are displayed in grayed meaning that can not be disabled. In our example you can see that "Notation item provider" is grayed. Indeed disabling it would produce incomprehensible results in EMF Compare UI on diagram comparisons. That's why its provider decided to prevents user from disabling it. All other elements can be enabled/disabled using the checkbox on the left of each label. For example the two other item providers can be disabled. If you want to know what an item provider is for, you can select it and a short description will appear in the "Description" field. For example, if you select "Stereotyped element item provider" you would read "This provider displays stereotyped elements like they were a new kind of UML element (it uses stereotype's icon and custom label)". This one can be disabled since without it a comparison result in EMF Compare UI would still be understandable for a user.
EMF Compare does not act simply on the selected files, but on their whole logical model (a given model can be split through multiple files through EMF control action). Thanks to that, if you try and compare a model file that reference other model files, the comparison will still be able to take these "other" files into account. For example, if you try and compare a genmodel file (that depends on its underlying ecore file), then both files will be taken into account for the comparison.
For more details about the logical model, please visit the Logical model page.
The EMF compare Logical Model View allows to see, for a given model (or set of models), the resulting logical model computed by EMF Compare.
The view is accessible from Window > Show View > Other ... > EMF Compare > Logical Model View.
When you click on a model in the Package Explorer view or the Project Explorer view, or the focus is on an opened model editor, then the Logical Model view shows this model and all models linked with this one.
While computing the logical model for a given model, the view shows the progression of computing.
1. The button Link with Editor and Selection synchronize the Logical Model View to the active editor or the selected element in the Package Explorer View.
2. The button View Menu
A contextual menu is accessible on each item displayed in the view. Through this menu, you will able to open the item selected, access to its properties, compare it, etc...
Here is the list of all open bugs of EMF Compare: EMF Compare bugs
Developments to compare shared models (via EGit) are not all included in offical releases EGit and EMF Compare yet. In order to let the customers to benefit such type of comparisons, you can download and install in your eclipse environment customs builds of EGit and EMF Compare that includes these additionnal developments. Note that the developments to fully supports comparisons with shared models via EGit are not finished yet: the results might be not relevant. Here are the update sites: