Jump to: navigation, search

Difference between revisions of "EMF Compare/User Guide"

(Installing EMF Compare)
(Cause)
(13 intermediate revisions by the same user not shown)
Line 20: Line 20:
 
   http://download.eclipse.org/releases/helios
 
   http://download.eclipse.org/releases/helios
 
   http://download.eclipse.org/releases/galileo
 
   http://download.eclipse.org/releases/galileo
 +
 +
The [http://www.eclipse.org/emf/compare/downloads/ Download page] lists more specific update sites if you wish to try one of the latest integration builds.
 +
 +
'''Compatibility'''
  
 
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 :  
 
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 :  
 +
 
{| border="1"
 
{| border="1"
 
|-
 
|-
 
! EMF Compare  
 
! EMF Compare  
 +
! bgcolor="#cccccc" | 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  
 
! 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
+
| bgcolor="#cccccc" | 2.1
| style="text-align:center; background:green; color:white" | OK
+
| style="text-align:center; background:#46a546; color:white" |  
|  
+
| style="text-align:center; background:#46a546; color:white" |  
|  
+
| style="text-align:center; background:#46a546; color:white" |  
|  
+
| style="text-align:center; background:#46a546; color:white" |  
|  
+
| style="text-align:center; background:#46a546; color:white" |  
|  
+
| style="text-align:center; background:#46a546; color:white" |  
|  
+
| style="text-align:center; background:#9d261d; color:white" |
 +
| style="text-align:center; background:#9d261d; color:white" |
 +
| style="text-align:center; background:#9d261d; color:white" |  
 
|-
 
|-
| 0.8
+
| 2.0
| style="text-align:center; background:red; color:white" | KO
+
| style="text-align:center; background:green; color:white" | OK
+
| style="text-align:center; background:green; color:white" | OK
+
|
+
|
+
|
+
 
|  
 
|  
 +
| style="text-align:center; background:#46a546; color:white" |
 +
| style="text-align:center; background:#46a546; color:white" |
 +
| style="text-align:center; background:#46a546; color:white" |
 +
| style="text-align:center; background:#46a546; color:white" |
 +
| style="text-align:center; background:#46a546; color:white" |
 +
| style="text-align:center; background:#9d261d; color:white" |
 +
| style="text-align:center; background:#9d261d; color:white" |
 +
| style="text-align:center; background:#9d261d; color:white" |
 
|-
 
|-
| 1.0
+
| 1.3
| style="text-align:center; background:red; color:white" | KO
+
| style="text-align:center; background:#9d261d; color:white" |  
| style="text-align:center; background:green; color:white" | OK
+
| style="text-align:center; background:#9d261d; color:white" |  
| style="text-align:center; background:green; color:white" | OK
+
| style="text-align:center; background:#46a546; color:white" |  
| style="text-align:center; background:green; color:white" | OK
+
| style="text-align:center; background:#46a546; color:white" |  
| style="text-align:center; background:green; color:white" | OK
+
| style="text-align:center; background:#46a546; color:white" |  
 +
| style="text-align:center; background:#46a546; color:white" |
 +
| style="text-align:center; background:#9d261d; color:white" |
 +
| style="text-align:center; background:#9d261d; color:white" |
 +
| style="text-align:center; background:#9d261d; color:white" |
 +
|-
 +
| 1.2
 
|  
 
|  
 
|  
 
|  
 +
| style="text-align:center; background:#46a546; color:white" | 
 +
| style="text-align:center; background:#46a546; color:white" | 
 +
| style="text-align:center; background:#46a546; color:white" | 
 +
| style="text-align:center; background:#46a546; color:white" | 
 +
| style="text-align:center; background:#46a546; color:white" |
 +
| style="text-align:center; background:#9d261d; color:white" | 
 +
| style="text-align:center; background:#9d261d; color:white" |
 
|-
 
|-
 
| 1.1  
 
| 1.1  
| style="text-align:center; background:red; color:white" | KO
+
|
| style="text-align:center; background:red; color:white" | KO
+
|
| style="text-align:center; background:green; color:white" | OK
+
| style="text-align:center; background:#46a546; color:white" |
| style="text-align:center; background:green; color:white" | OK
+
| style="text-align:center; background:#46a546; color:white" |
| style="text-align:center; background:green; color:white" | OK
+
| style="text-align:center; background:#46a546; color:white" |
| style="text-align:center; background:green; color:white" | OK
+
| style="text-align:center; background:#46a546; color:white" |
| style="text-align:center; background:green; color:white" | OK
+
| style="text-align:center; background:#46a546; color:white" |  
 +
| style="text-align:center; background:#9d261d; color:white" |
 +
| style="text-align:center; background:#9d261d; color:white" |  
 
|-
 
|-
| 1.2
+
| 1.0
| style="text-align:center; background:red; color:white" | KO
+
|  
| style="text-align:center; background:red; color:white" | KO
+
|  
| style="text-align:center; background:green; color:white" | OK
+
|  
| style="text-align:center; background:green; color:white" | OK
+
|
| style="text-align:center; background:green; color:white" | OK
+
| style="text-align:center; background:#46a546; color:white" |  
| style="text-align:center; background:green; color:white" | OK
+
| style="text-align:center; background:#46a546; color:white" |  
| style="text-align:center; background:green; color:white" | OK
+
| style="text-align:center; background:#46a546; color:white" |  
|-
+
| style="text-align:center; background:#46a546; color:white" |  
| 1.3
+
| style="text-align:center; background:#9d261d; color:white" |
| style="text-align:center; background:red; color:white" | KO
+
| style="text-align:center; background:red; color:white" | KO
+
| style="text-align:center; background:red; color:white" | KO
+
| style="text-align:center; background:green; color:white" | OK
+
| style="text-align:center; background:green; color:white" | OK
+
| style="text-align:center; background:green; color:white" | OK
+
| style="text-align:center; background:green; color:white" | OK
+
|-
+
| bgcolor="#cccccc" | 2.0
+
| style="text-align:center; background:red; color:white" | KO
+
| style="text-align:center; background:red; color:white" | KO
+
| style="text-align:center; background:red; color:white" | KO
+
| style="text-align:center; background:green; color:white" |OK
+
| style="text-align:center; background:green; color:white" | OK
+
| style="text-align:center; background:green; color:white" | OK
+
| style="text-align:center; background:green; color:white" | OK
+
 
|}
 
|}
  
 
An empty cell indicates that the compatibility hasn't been tested for a particular combination.
 
An empty cell indicates that the compatibility hasn't been tested for a particular combination.
 +
 +
== User Interface Breakdown ==
 +
 +
The main points of interest are highlighted in the following picture :
 +
 +
[[Image:CompareUI.png|center|EMF Compare's basic user interface]]
 +
 +
# 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.
  
 
== Usage ==
 
== Usage ==
Line 105: Line 131:
 
[[Image:EMFC Compare With.png|center]]
 
[[Image:EMFC Compare With.png|center]]
  
=== Sample Use Case ===
+
The following displays the important part of a model life cycle with regards to the comparison. The full life cycle can be followed on [[EMF Compare/Sample Use Case]]
 
+
With the following, we'll follow the life cycle of a metamodel describing a very basic library as it evolves separately in different branches. This will allow us to give more concrete examples of how EMF Compare can be used, and how it can help you.
+
  
==== Creating a model ====
+
=== Compare with latest ===
  
 
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.
 
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.
Line 116: Line 140:
 
* library_Types.uml will contain our primitive types,
 
* library_Types.uml will contain our primitive types,
 
* library.uml will contain our actual model.
 
* library.uml will contain our actual model.
 
The two models will be commited to our git clone. The whole thing looks like this :
 
 
[[Image:EMF Compare Use Setup.png]]
 
  
 
The model itself is a very simple library. Graphically speaking :
 
The model itself is a very simple library. Graphically speaking :
Line 125: Line 145:
 
[[Image:EMF Compare Use Model.png]]
 
[[Image:EMF Compare Use Model.png]]
  
Now that this initial model file has been committed, we'd like to improve it a little. For example :
+
We commit this initial file as the original model. We then slightly modify it so that it now looks like :
* 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 :
+
  
 
[[Image:EMF Compare Use Model Changed.png]]
 
[[Image:EMF Compare Use Model Changed.png]]
Line 138: Line 153:
 
[[Image:EMF Compare Use Compare 1.png]]
 
[[Image:EMF Compare Use Compare 1.png]]
  
This will open a comparison editor that initially looks like the following :
+
This will open a comparison editor that initially displays empty panels on its bottom half. Let's select one of the differences displayed on its top half :
 
+
[[Image:EMF Compare Use Compare 2.png]]
+
 
+
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. This is originally empty, more on this section in the example just below.
+
# 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. This is originally empty, more on this section in the example just below.
+
 
+
As stated above, (2) and (3) are initially empty. These two panels are there to display more information about the differences detected between our models. Let's select one of the differences displayed in (1) :
+
  
 
[[Image:EMF Compare Use Compare 3.png]]
 
[[Image:EMF Compare Use Compare 3.png]]
Line 157: Line 163:
 
# This panel displays all values of the reference outlined in (4) as they are in the ''right'' model. In here, we see the location of '''alias''' outlined as an empty space. This rectangle is where the new value will be added if we merge it... Though in this case, it is not possible to merge towards the ''right'' : it is a version located on a repository and is thus non-editable.
 
# This panel displays all values of the reference outlined in (4) as they are in the ''right'' model. In here, we see the location of '''alias''' outlined as an empty space. This rectangle is where the new value will be added if we merge it... Though in this case, it is not possible to merge towards the ''right'' : it is a version located on a repository and is thus non-editable.
  
This is useful in order to determine exactly what changed in our version, but serves no other purpose : merging changes here would only mean reverting back our modifications to the "clean" state from the repository. Let's commit our changes.
+
This is useful in order to determine exactly what changed in our version, but serves no other purpose : merging changes here would only mean reverting back our modifications to the "clean" state from the repository. Let's commit our changes on the ''master'' branch.
  
==== Branching ====
+
=== Compare two differing branches ===
  
Now, we'd like to create a new feature for our library : we'd like clients to be able to borrow our books. We'll branch our repository in order to create this new feature and name this new branch ''borrowables'' :
+
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) :
  
[[Image:EMF Compare Use Compare 4.png]]
+
{| border="1" cellpadding="5" cellspacing="0" align="center"
 +
|-
 +
! align="center" | Master
 +
! align="center" | Borrowables
 +
|-
 +
| [[Image:EMF Compare Use Compare Master.png|center]]
 +
| [[Image:EMF Compare Use Compare 5.png|center]]
 +
|}
  
Starting right away, we add the necessary new concepts to our model to represent the possibility of lending books. We "may" later need to have more than books to be lendable, so let's make a ''Borrowable'' interface to hold this concept. We'll also need a ''Person'' class, as well as a new data type to represent the person's birth date :
+
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 :
  
[[Image:EMF Compare Use Compare 5.png]]
+
[[Image:EMF Compare Use Compare With Master 1.png|center]]
  
In a tree viewer, our models now look like (highlighted in red, the concepts we added with this step) :
+
and compare with master :
  
[[Image:EMF Compare Use Compare 6.png]]
+
[[Image:EMF Compare Use Compare With Master 2.png|center]]
  
However, while we are working on our ''borrowables'' branch, the ''master'' branch may still evolve : other people on the project might be adding new concepts of their own, or we could be switching to the main branch for a high priority fix ourselves. Let's imagine that two features have been added since we branched our repository. First, someone needed to have the library hold not only Books, but also Magazines. Second, we needed the publication date of our Books and magazines to be recorded.
+
This shows us all differences between our local copy and the master branch that were made since the 'branching' point.
  
The first of these two commits will add the following concepts to our ''master'' branch's model :
+
[[Image:EMF Compare Merge.png|center]]
  
[[Image:EMF Compare Use Compare 7.png]]
+
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 ([[Image:EMF Compare Incoming Change.gif]]) or a derived icon, and '''outgoing''' differences decorated with a green arrow ([[Image:EMF Compare Outgoing Change.gif]]) or a derived icon.
  
While the second only adds a primitive type and a property :
+
* '''Incoming''' differences are changes that were made in the remote branch (here, ''master'') since the branching point (common ancestor).
 +
* '''Outgoing''' differences are changes taht were made in the local copy (here, the ''borrowables'' branch) since the branching point.
  
[[Image:EMF Compare Use Compare 8.png]]
+
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.
  
==== Merge ====
+
The interface also lets you display the common ancestor of both models through the [[Image:EMF Compare Ancestor.gif]] icon. For example, if we select the '''Book''' class, we can see how it looks like on all three versions :
  
If you have followed to this point, we now have two diverging branches, ''master'' and ''borrowables'' which both hold a different version of our ''library.uml'' model. Here is how these two models look like at this point :
+
[[Image:EMF Compare Merge Book Ancestor.png|center]]
  
{| border="1" cellpadding="5" cellspacing="0" align="center"
+
You can navigate through the differences using the appropriate actions, either the previous ([[Image:EMF Compare Prev Diff.gif]]) or the next ([[Image:EMF Compare Next Diff.gif]]) difference.
|-
+
! align="center" | Master
+
! align="center" | Borrowables
+
|-
+
| [[Image:EMF Compare Use Compare Master.png|center]]
+
| [[Image:EMF Compare Use Compare 5.png|center]]
+
|}
+
  
== User Interface  ==
+
The remaining two actions are those that actually interest us here we can either merge all non-conflicting differences to the local copy through [[Image:EMF Compare Copy All.gif]] or merge them one after the other through [[Image:EMF Compare Copy.gif]].
  
The main points of interest are highlighted in the following picture :
+
Merging '''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 one after the other and merge them one by one. This gives us our merged model :
  
[[Image:CompareUI.png|center|EMF Compare's basic user interface]]
+
[[Image:EMF Compare Merged.png|center]]
  
# Overview of the differences detected between the given two (or three) models.
+
Notice that ''merged'' differences are displayed in ''italics'' and have a distinct icon. All that's left is to save, our model now contains both our local changes and the changes that were made on master.
# 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 =
 
= Features =
Line 292: Line 291:
  
 
[http://www.eclipse.org/emf/compare/doc/features/videos/UML%20comparison/compareUml.htm [Demo : Specific support to encapsulate profiles and stereotypes diffs]]
 
[http://www.eclipse.org/emf/compare/doc/features/videos/UML%20comparison/compareUml.htm [Demo : Specific support to encapsulate profiles and stereotypes diffs]]
 +
 +
= Known bugs and limitations =
 +
 +
== Project names and location ==
 +
 +
'''Project names should match their location'''
 +
 +
=== Cause ===
 +
 +
If you need to compare models that:
 +
* reference another model in the same project (or another project which also meets the following point), and
 +
* are located in a project which name (as seen in their '.project' file) does not match their containing folder's name (case sensitive).
 +
 +
Due to [https://bugs.eclipse.org/bugs/show_bug.cgi?id=354801 Bug 354801], we cannot properly support models that are located in Eclipse projects which identifier is distinct from their containing folder, case included. For example, if you have a project named ''EcoreModels'', it '''must''' be contained in a folder named ''EcoreModels''. Any other name, even if changing only the case, such as ''ecoreModels'', will cause issues when comparing fragmented models (or any model which references another).
 +
 +
Note that this only applies to comparisons launched from within Eclipse, which would trigger the opening of the EMF Compare user interface.
 +
 +
=== Observed Symptoms ===
 +
 +
Symptoms vary, but they often include a NullPointerException somewhere in EMFSynchronizationModel such as :
 +
 +
Caused by: java.lang.NullPointerException
 +
at org.eclipse.emf.compare.ide.ui.logical.RevisionedURIConverter.<init>(RevisionedURIConverter.java:108)
 +
at org.eclipse.emf.compare.ide.ui.logical.EMFSynchronizationModel.resolveTraversal(EMFSynchronizationModel.java:464)
 +
at org.eclipse.emf.compare.ide.ui.logical.EMFSynchronizationModel.createSynchronizationModel(EMFSynchronizationModel.java:165)
 +
at org.eclipse.emf.compare.ide.ui.internal.structuremergeviewer.EMFCompareStructureMergeViewer.compareInputChanged(EMFCompareStructureMergeViewer.java:258)
 +
 +
== Models out of the workspace ==
 +
 +
'''The models should be imported within the workspace'''
 +
 +
=== Cause ===
 +
 +
Trying to compare models that are not present in the current Eclipse workspace from either the ''Git repositories'' perspective, or from the ''Git Staging'' view.
 +
 +
Note that this only applies to comparisons launched from within Eclipse, which would trigger the opening of the EMF Compare user interface.
 +
 +
=== Observed Symptoms ===
 +
 +
Symptoms are mostly the same here as they would be with the limitation mentionned above regarding project names, and they usually include the same NullPointerException:
 +
 +
Caused by: java.lang.NullPointerException
 +
at org.eclipse.emf.compare.ide.ui.logical.RevisionedURIConverter.<init>(RevisionedURIConverter.java:108)
 +
at org.eclipse.emf.compare.ide.ui.logical.EMFSynchronizationModel.resolveTraversal(EMFSynchronizationModel.java:464)
 +
at org.eclipse.emf.compare.ide.ui.logical.EMFSynchronizationModel.createSynchronizationModel(EMFSynchronizationModel.java:165)
 +
at org.eclipse.emf.compare.ide.ui.internal.structuremergeviewer.EMFCompareStructureMergeViewer.compareInputChanged(EMFCompareStructureMergeViewer.java:258)
  
 
= Other Materials  =
 
= Other Materials  =

Revision as of 04:37, 6 March 2013


EMF Compare
Website
Download
Community
Mailing List
Forums
Bugzilla
Open
Create New
Contribute
Browse Source


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.


Marketplace.png

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/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.

Compatibility

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 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
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.

User Interface Breakdown

The main points of interest are highlighted in the following picture :

EMF Compare's basic user interface
  1. Overview of the differences detected between the given two (or three) models.
  2. First version of the compared models.
  3. Second version of the compared models.
  4. 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.
  5. This button will allow you to group differences together in the structural view. For example, grouping all "Additions" or "Deletions" together.
  6. 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".
  7. Allows you to merge all non conflicting differences (left to right, or right to left) at once.
  8. Allows you to merge the single, currently selected difference in a given direction (left to right, or right to left).
  9. Allows you to navigate through the detected differences.

Usage

Once installed, you can compare your files (locally or from any Version Control System) as usual using the compare with menu.

EMFC Compare With.png

The following displays the important part of a model life cycle with regards to the comparison. The full life cycle can be followed on EMF Compare/Sample Use Case

Compare with latest

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 model itself is a very simple library. Graphically speaking :

EMF Compare Use Model.png

We commit this initial file as the original model. We then slightly modify it so that it now looks like :

EMF Compare Use Model Changed.png

But how do we know exactly what changed? Let's compare this with the file from the Git Index :

EMF Compare Use Compare 1.png

This will open a comparison editor that initially displays empty panels on its bottom half. Let's select one of the differences displayed on its top half :

EMF Compare Use Compare 3.png

  1. 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.
  2. alias has been added to the properties of Class Writer. In the model, this corresponds to a change to the reference ownedAttributes of the Writer Class. This sub-panel indicates the actual reference that was changed in oder to remind us of the context.
  3. This displays all values of the reference outlined in (2) as they are in the left model. This is where we see the new value, alias outlined.
  4. As for (2), this will display the context of the selected difference. The same reference will usually be displayed in both (2) and (4).
  5. This panel displays all values of the reference outlined in (4) as they are in the right model. In here, we see the location of alias outlined as an empty space. This rectangle is where the new value will be added if we merge it... Though in this case, it is not possible to merge towards the right : it is a version located on a repository and is thus non-editable.

This is useful in order to determine exactly what changed in our version, but serves no other purpose : merging changes here would only mean reverting back our modifications to the "clean" state from the repository. Let's commit our changes on the master branch.

Compare two differing branches

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
EMF Compare Use Compare Master.png
EMF Compare Use Compare 5.png

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 :

EMF Compare Use Compare With Master 1.png

and compare with master :

EMF Compare Use Compare With Master 2.png

This shows us all differences between our local copy and the master branch that were made since the 'branching' point.

EMF Compare Merge.png

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 (EMF Compare Incoming Change.gif) or a derived icon, and outgoing differences decorated with a green arrow (EMF Compare Outgoing Change.gif) 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 taht 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 EMF Compare Ancestor.gif icon. For example, if we select the Book class, we can see how it looks like on all three versions :

EMF Compare Merge Book Ancestor.png

You can navigate through the differences using the appropriate actions, either the previous (EMF Compare Prev Diff.gif) or the next (EMF Compare Next Diff.gif) difference.

The remaining two actions are those that actually interest us here we can either merge all non-conflicting differences to the local copy through EMF Compare Copy All.gif or merge them one after the other through EMF Compare Copy.gif.

Merging 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 one after the other and merge them one by one. This gives us our merged model :

EMF Compare Merged.png

Notice that merged differences are displayed in italics and have a distinct icon. All that's left is to save, our model now contains both our local changes and the changes that were made on master.

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 : EMF Compare Groups Choice.png

Default 
Do not try and group differences together, display them as they were detected.

EMF Compare Groups Default.png

By Kind 
Group differences by their kind (additions, deletions, moves, changes).

EMF Compare Groups Kind.png

By Metaclass 
Group difference according to the metaclass of the object on which they were detected.

EMF Compare Groups Metaclass.png

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 : EMF Compare Filters Choice.png

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.

EMF Compare Text Compare.png

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]

Diag comp diff.png

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 Logical Compare Action.png

EMF Compare will actually consider both files when comparing :

EMF Compare Logical Compare Result.png

PENDING UPDATE Demo

UML Specialization

PENDING

[Demo : Specific support to encapsulate profiles and stereotypes diffs]

Known bugs and limitations

Project names and location

Project names should match their location

Cause

If you need to compare models that:

  • reference another model in the same project (or another project which also meets the following point), and
  • are located in a project which name (as seen in their '.project' file) does not match their containing folder's name (case sensitive).

Due to Bug 354801, we cannot properly support models that are located in Eclipse projects which identifier is distinct from their containing folder, case included. For example, if you have a project named EcoreModels, it must be contained in a folder named EcoreModels. Any other name, even if changing only the case, such as ecoreModels, will cause issues when comparing fragmented models (or any model which references another).

Note that this only applies to comparisons launched from within Eclipse, which would trigger the opening of the EMF Compare user interface.

Observed Symptoms

Symptoms vary, but they often include a NullPointerException somewhere in EMFSynchronizationModel such as :

Caused by: java.lang.NullPointerException
at org.eclipse.emf.compare.ide.ui.logical.RevisionedURIConverter.<init>(RevisionedURIConverter.java:108)
at org.eclipse.emf.compare.ide.ui.logical.EMFSynchronizationModel.resolveTraversal(EMFSynchronizationModel.java:464)
at org.eclipse.emf.compare.ide.ui.logical.EMFSynchronizationModel.createSynchronizationModel(EMFSynchronizationModel.java:165)
at org.eclipse.emf.compare.ide.ui.internal.structuremergeviewer.EMFCompareStructureMergeViewer.compareInputChanged(EMFCompareStructureMergeViewer.java:258)

Models out of the workspace

The models should be imported within the workspace

Cause

Trying to compare models that are not present in the current Eclipse workspace from either the Git repositories perspective, or from the Git Staging view.

Note that this only applies to comparisons launched from within Eclipse, which would trigger the opening of the EMF Compare user interface.

Observed Symptoms

Symptoms are mostly the same here as they would be with the limitation mentionned above regarding project names, and they usually include the same NullPointerException:

Caused by: java.lang.NullPointerException
at org.eclipse.emf.compare.ide.ui.logical.RevisionedURIConverter.<init>(RevisionedURIConverter.java:108)
at org.eclipse.emf.compare.ide.ui.logical.EMFSynchronizationModel.resolveTraversal(EMFSynchronizationModel.java:464)
at org.eclipse.emf.compare.ide.ui.logical.EMFSynchronizationModel.createSynchronizationModel(EMFSynchronizationModel.java:165)
at org.eclipse.emf.compare.ide.ui.internal.structuremergeviewer.EMFCompareStructureMergeViewer.compareInputChanged(EMFCompareStructureMergeViewer.java:258)

Other Materials