Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
EMF Compare/User Guide
EMF Compare |
Website |
Download |
Community |
Mailing List |
Forums |
Bugzilla |
Open |
Create New |
Contribute |
Browse Source |
Contents
Getting Started
Installing EMF Compare
Marketplace Client
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.
Update Site
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/galileo http://download.eclipse.org/releases/helios http://download.eclipse.org/releases/indigo http://download.eclipse.org/releases/juno
Please note that the EMF Compare development team does its best to maintain downward compatibility towards Galileo (Eclipse 3.5). Following is the compatibility chart :
EMF Compare | Eclipse 3.2 - EMF 2.2 | Eclipse 3.3 - EMF 2.3 | Eclipse 3.4 - EMF 2.4 | Eclipse 3.5 - EMF 2.5 | Eclipse 3.6 - EMF 2.6 | Eclipse 3.7 - EMF 2.7 | Eclipse 3.8 - EMF 2.8 |
---|---|---|---|---|---|---|---|
0.7 | OK | ||||||
0.8 | KO | OK | OK | ||||
1.0 | KO | OK | OK | OK | OK | ||
1.1 | KO | KO | OK | OK | OK | OK | OK |
1.2 | KO | KO | OK | OK | OK | OK | OK |
1.3 | KO | KO | KO | OK | OK | OK | OK |
2.0 | KO | KO | KO | OK | OK | OK | OK |
An empty cell indicates that the compatibility hasn't been tested for a particular combination.
Usage
Once installed, you can compare your files (locally or from any Version Control System) as usual using the compare with menu.
Sample Use Case
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 :
- library_Types.uml will contain our primitive types,
- library.uml will contain our actual model.
The two models will be commited to our git clone. The whole thing looks like this :
The model itself is a very simple library. Graphically speaking :
Now that this initial model file has been committed, we'd like to improve it a little. For example :
- Add an alias property to the Writer class,
- Add a new History Category,
- Rename the pages property of Book into length.
Our model now looks like this :
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 that initially looks like the following :
There are three main areas of interest in this editor.
- . Displays a structured list of the differences detected between the current version of the model and the version that lies in the Git Index.
- . This will react to the selections in (1) and display the left side of this comparison. As a rule of thumb, the left is the local version of the model. In this example, left will then be the version we have modified in our workspace.
- . As above, this will react to selections in (1), but this time it will display the right side of the comparison. This is generally the remote version of the model; the version to which we've compared ours. In this case, this will represent the version of the model as it is in the Git Index.
(2) and (3) are initially empty. They are there to display more information about the differences detected between our models. Let's select one of these differences :
- . We've selected the difference corresponding to the addition of attribute alias in the class Writer. A double-click on this difference updated our two panes below.
- .
User Interface
The main points of interest are highlighted in the following picture :
- Overview of the differences detected between the given two (or three) models.
- First version of the compared models.
- Second version of the compared models.
- This button will only be visible in the case of three-way comparisons (for example, comparing with a remote repository). It will make a third version of the compared model (the common ancestor of the two others) visible in the interface.
- This button will allow you to group differences together in the structural view. For example, grouping all "Additions" or "Deletions" together.
- This button will allow you to filter some differences out of the view according to a set predicate. For example, filtering out all "Additions" or "Moves".
- Allows you to merge all non conflicting differences (left to right, or right to left) at once.
- Allows you to merge the single, currently selected difference in a given direction (left to right, or right to left).
- Allows you to navigate through the detected differences.
Features
Handling Conflicts
PENDING
Grouping Differences
This feature allows you to group differences together in the structural view according to a set predicate. By default, EMF Compare provides three distinct grouping strategies :
- Default
- Do not try and group differences together, display them as they were detected.
- By Kind
- Group differences by their kind (additions, deletions, moves, changes).
- By Metaclass
- Group difference according to the metaclass of the object on which they were detected.
PENDING UPDATE, this is a demo displaying EMF Compare 1.3 Demo
PENDING : New grouping strategies can be provided to EMF Compare through extension points.
Filtering Differences
This features allows you to filter differences out of the structural view according to a set predicate. By default, EMF Compare provides five distinct filters :
- Changed Elements
- Filter out all differences of type CHANGE. Disabled by default.
- Added Elements
- Filter out all differences of type ADD. Disabled by default.
- Removed Elements
- Filter out all differences of type DELETE. Disabled by default.
- Moved Elements
- Filter out all differences of type CHANGE. Disabled by default.
- Resource Mappings
- Filter out all resource mappings from the view. Enabled by default.
PENDING UPDATE, this is a demo displaying EMF Compare 1.3 Demo
PENDING : New filters can be provided to EMF Compare through extension points.
Text Attribute Comparison
Differences made into String-typed attributes can be compared and merged directly as text from the compare interface through a simple right-click on the difference.
PENDING UPDATE, this demo displays EMF Compare 1.3 Demo
Graphical Comparison
PENDING UPDATE
Since the 1.2 release EMF compare provides the ability to compare models with graphical modelers.
Have a look on the following demos :
[Demo : Comparing Ecore files with diagrams]
[Demo : Comparing UML files with diagrams]
Logical Model
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
UML Specialization
PENDING
[Demo : Specific support to encapsulate profiles and stereotypes diffs]