documentation/3.1.0.201505180755/user/user-guide.html - gerrit/www.eclipse.org/emf/compare

blob: a8aee74443f91298114aef8c14b4af9bcdbf1323 [file] [log] [blame]

	<?xml version='1.0' encoding='utf-8' ?>
	<html xmlns="http://www.w3.org/1999/xhtml">
	<head>
	<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
	<title>User guide</title>
	<style type="text/css">
	.tip {border: 1px solid #090;background-color: #dfd;margin: 20px;padding: 0px 6px 0px 6px;}
	.warning {border: 1px solid #c00;background-color: #fcc;margin: 20px;padding: 0px 6px 0px 6px;}
	.panel {border: 1px solid #ccc;background-color: #FFFFCE;margin: 10px;padding: 0px 6px 0px 6px;}
	.note {border: 1px solid #F0C000;background-color: #FFFFCE;margin: 20px;padding: 0px 6px 0px 6px;}
	.info {border: 1px solid #3c78b5;background-color: #D8E4F1;margin: 20px;padding: 0px 6px 0px 6px;}
	</style>
	<link type="text/css" rel="stylesheet" href="../resources/bootstrap.css"/>
	<link type="text/css" rel="stylesheet" href="../resources/custom.css"/>
	</head>
	<body>
	<h1 id="EMF_Compare_.E2.80.94__User_Guide">EMF Compare — User Guide</h1>
	<p>Version 3.2.0.201505180755</p>
	<div class="toc">
	<h3 class="toc-title">Table of Contents</h3>
	<ol style="list-style: none">
	<li>
	<a href="#Getting_Started">Getting Started</a>
	<ol style="list-style: none">
	<li>
	<a href="#Installing_EMF_Compare">Installing EMF Compare</a>
	<ol style="list-style: none">
	<li>
	<a href="#Marketplace_Client">Marketplace Client</a>
	</li>
	<li>
	<a href="#Update_Site">Update Site</a>
	</li>
	<li>
	<a href="#Compatibility">Compatibility</a>
	</li>
	</ol>
	</li>
	<li>
	<a href="#User_Interface_Breakdown">User Interface Breakdown</a>
	<ol style="list-style: none">
	<li>
	<a href="#Toolbar">Toolbar</a>
	</li>
	<li>
	<a href="#Signification_of_icons_associated_with_differences">Signification of icons associated with differences</a>
	</li>
	<li>
	<a href="#After_merge">After merge</a>
	</li>
	<li>
	<a href="#Items_for_not_loaded_fragments">Items for not loaded fragments</a>
	</li>
	</ol>
	</li>
	</ol>
	</li>
	<li>
	<a href="#Launch_Comparison">Launch Comparison</a>
	<ol style="list-style: none">
	<li>
	<a href="#Compare_with_local_models">Compare with local models</a>
	<ol style="list-style: none">
	<li>
	<a href="#Compare_with_each_other">Compare with each other</a>
	</li>
	<li>
	<a href="#Compare_with_local_history">Compare with local history</a>
	</li>
	</ol>
	</li>
	<li>
	<a href="#Compare_with_remote_models_.28EGit.29">Compare with remote models (EGit)</a>
	<ol style="list-style: none">
	<li>
	<a href="#Compare_with_latest">Compare with latest</a>
	</li>
	<li>
	<a href="#Compare_two_differing_branches">Compare two differing branches</a>
	</li>
	<li>
	<a href="#Resource_name_changes">Resource name changes</a>
	</li>
	</ol>
	</li>
	</ol>
	</li>
	<li>
	<a href="#Customization">Customization</a>
	<ol style="list-style: none">
	<li>
	<a href="#Engines">Engines</a>
	<ol style="list-style: none">
	<li>
	<a href="#Match_Engine">Match Engine</a>
	<ol style="list-style: none">
	<li>
	<a href="#Configure_registered_matching_engine">Configure registered matching engine</a>
	<ol style="list-style: none">
	<li>
	<a href="#Matching_strategy_for_default_match_engine">Matching strategy for default match engine</a>
	</li>
	</ol>
	</li>
	<li>
	<a href="#Enable.2FDisable_Match_Engines">Enable/Disable Match Engines</a>
	</li>
	</ol>
	</li>
	<li>
	<a href="#For_other_engines">For other engines</a>
	<ol style="list-style: none">
	<li>
	<a href="#Choose_the_default_engine">Choose the default engine</a>
	</li>
	</ol>
	</li>
	</ol>
	</li>
	<li>
	<a href="#Post_processors_customization">Post processors customization</a>
	<ol style="list-style: none">
	<li>
	<a href="#Model_Resolvers">Model Resolvers</a>
	<ol style="list-style: none">
	<li>
	<a href="#Choose_a_strategy">Choose a strategy</a>
	</li>
	<li>
	<a href="#Disable_model_resolution">Disable model resolution</a>
	</li>
	</ol>
	</li>
	</ol>
	</li>
	<li>
	<a href="#User_Interface_customization">User Interface customization</a>
	<ol style="list-style: none">
	<li>
	<a href="#Colors_Customization">Colors Customization</a>
	</li>
	<li>
	<a href="#Filters">Filters</a>
	</li>
	<li>
	<a href="#Groups">Groups</a>
	</li>
	<li>
	<a href="#Items_providers">Items providers</a>
	</li>
	</ol>
	</li>
	</ol>
	</li>
	<li>
	<a href="#Features">Features</a>
	<ol style="list-style: none">
	<li>
	<a href="#Grouping_Differences">Grouping Differences</a>
	</li>
	<li>
	<a href="#Filtering_Differences">Filtering Differences</a>
	</li>
	<li>
	<a href="#Handling_Conflicts">Handling Conflicts</a>
	</li>
	<li>
	<a href="#Text_Attribute_Comparison">Text Attribute Comparison</a>
	</li>
	<li>
	<a href="#Graphical_Comparison">Graphical Comparison</a>
	</li>
	<li>
	<a href="#Logical_Model">Logical Model</a>
	</li>
	<li>
	<a href="#UML_Specialization">UML Specialization</a>
	</li>
	</ol>
	</li>
	<li>
	<a href="#Logical_Model_View">Logical Model View</a>
	<ol style="list-style: none">
	<li>
	<a href="#Toolbar_2">Toolbar</a>
	</li>
	<li>
	<a href="#Contextual_Menu">Contextual Menu</a>
	</li>
	</ol>
	</li>
	<li>
	<a href="#Known_Bugs_and_Limitations">Known Bugs and Limitations</a>
	<ol style="list-style: none">
	<li>
	<a href="#Project_names_and_location">Project names and location</a>
	<ol style="list-style: none">
	<li>
	<a href="#Cause">Cause</a>
	</li>
	<li>
	<a href="#Observed_Symptoms">Observed Symptoms</a>
	</li>
	</ol>
	</li>
	<li>
	<a href="#Models_out_of_the_workspace">Models out of the workspace</a>
	<ol style="list-style: none">
	<li>
	<a href="#Cause_2">Cause</a>
	</li>
	<li>
	<a href="#Observed_Symptoms_2">Observed Symptoms</a>
	</li>
	</ol>
	</li>
	</ol>
	</li>
	<li>
	<a href="#Other_Materials">Other Materials</a>
	</li>
	</ol>
	</div>
	<h2 id="Getting_Started">Getting Started</h2>
	<h3 id="Installing_EMF_Compare">Installing EMF Compare</h3>
	<h4 id="Marketplace_Client">Marketplace Client</h4>
	<p>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. </p>
	<p>
	<img border="0" src="./../images/Marketplace.png"/>
	</p>
	<h4 id="Update_Site">Update Site</h4>
	<p>EMF has been part of the Eclipse release train since Galileo, you can install it using the following update sites, depending on your platform.
	<b>Note</b> that the following are not meant to be visited in your internet browser; they must be pasted in the
	<i>Help > Install New Software</i> dialog of your Eclipse, as p2 repositories.
	</p>
	<pre> <a href="http://download.eclipse.org/releases/mars">http://download.eclipse.org/releases/mars</a>
	<a href="http://download.eclipse.org/releases/luna">http://download.eclipse.org/releases/luna</a>
	<a href="http://download.eclipse.org/releases/kepler">http://download.eclipse.org/releases/kepler</a>
	<a href="http://download.eclipse.org/releases/juno">http://download.eclipse.org/releases/juno</a>
	<a href="http://download.eclipse.org/releases/indigo">http://download.eclipse.org/releases/indigo</a>
	<a href="http://download.eclipse.org/releases/helios">http://download.eclipse.org/releases/helios</a>
	<a href="http://download.eclipse.org/releases/galileo">http://download.eclipse.org/releases/galileo</a>
	</pre>
	<p>The
	<a href="http://www.eclipse.org/emf/compare/downloads/">Download page</a> lists more specific update sites if you wish to try one of the latest integration builds.
	</p>
	<h4 id="Compatibility">Compatibility</h4>
	<p>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 : </p>
	<table border="1">
	<tr>
	<th>EMF Compare </th>
	<th bgcolor="#cccccc" align="center">Eclipse 4.5 - EMF 2.11</th>
	<th align="center">Eclipse 4.4 - EMF 2.10</th>
	<th align="center">Eclipse 4.3 - EMF 2.9</th>
	<th align="center">Eclipse 4.2 - EMF 2.8</th>
	<th align="center">Eclipse 3.8 - EMF 2.8</th>
	<th align="center">Eclipse 3.7 - EMF 2.7</th>
	<th align="center">Eclipse 3.6 - EMF 2.6</th>
	<th align="center">Eclipse 3.5 - EMF 2.5</th>
	<th align="center">Eclipse 3.4 - EMF 2.4</th>
	<th align="center">Eclipse 3.3 - EMF 2.3</th>
	<th align="center">Eclipse 3.2 - EMF 2.2</th>
	</tr>
	<tr>
	<td bgcolor="#cccccc" align="center">3.1</td>
	<td bgcolor="#46a546"> </td>
	<td bgcolor="#46a546"> </td>
	<td bgcolor="#46a546"> </td>
	<td bgcolor="#46a546"> </td>
	<td bgcolor="#46a546"> </td>
	<td bgcolor="#46a546"> </td>
	<td bgcolor="#46a546"> </td>
	<td bgcolor="#9d261d"> </td>
	<td bgcolor="#9d261d"> </td>
	<td bgcolor="#9d261d"> </td>
	<td bgcolor="#9d261d"> </td>
	</tr>
	<tr>
	<td bgcolor="#ffffff" align="center">3.0</td>
	<td bgcolor="#ffffff"> </td>
	<td bgcolor="#46a546"> </td>
	<td bgcolor="#46a546"> </td>
	<td bgcolor="#46a546"> </td>
	<td bgcolor="#46a546"> </td>
	<td bgcolor="#46a546"> </td>
	<td bgcolor="#46a546"> </td>
	<td bgcolor="#9d261d"> </td>
	<td bgcolor="#9d261d"> </td>
	<td bgcolor="#9d261d"> </td>
	<td bgcolor="#9d261d"> </td>
	</tr>
	<tr>
	<td align="center">2.1</td>
	<td bgcolor="#ffffff"> </td>
	<td bgcolor="#ffffff"> </td>
	<td bgcolor="#46a546"> </td>
	<td bgcolor="#46a546"> </td>
	<td bgcolor="#46a546"> </td>
	<td bgcolor="#46a546"> </td>
	<td bgcolor="#46a546"> </td>
	<td bgcolor="#46a546"> </td>
	<td bgcolor="#9d261d"> </td>
	<td bgcolor="#9d261d"> </td>
	<td bgcolor="#9d261d"> </td>
	</tr>
	<tr>
	<td align="center">2.0</td>
	<td bgcolor="#ffffff"> </td>
	<td bgcolor="#ffffff"> </td>
	<td bgcolor="#ffffff"> </td>
	<td bgcolor="#46a546"> </td>
	<td bgcolor="#46a546"> </td>
	<td bgcolor="#46a546"> </td>
	<td bgcolor="#46a546"> </td>
	<td bgcolor="#46a546"> </td>
	<td bgcolor="#9d261d"> </td>
	<td bgcolor="#9d261d"> </td>
	<td bgcolor="#9d261d"> </td>
	</tr>
	<tr>
	<td align="center">1.3</td>
	<td bgcolor="#9d261d"> </td>
	<td bgcolor="#9d261d"> </td>
	<td bgcolor="#9d261d"> </td>
	<td bgcolor="#9d261d"> </td>
	<td bgcolor="#46a546"> </td>
	<td bgcolor="#46a546"> </td>
	<td bgcolor="#46a546"> </td>
	<td bgcolor="#46a546"> </td>
	<td bgcolor="#9d261d"> </td>
	<td bgcolor="#9d261d"> </td>
	<td bgcolor="#9d261d"> </td>
	</tr>
	<tr>
	<td align="center">1.2 </td>
	<td bgcolor="#ffffff"> </td>
	<td bgcolor="#ffffff"> </td>
	<td bgcolor="#ffffff"> </td>
	<td bgcolor="#ffffff"> </td>
	<td bgcolor="#46a546"> </td>
	<td bgcolor="#46a546"> </td>
	<td bgcolor="#46a546"> </td>
	<td bgcolor="#46a546"> </td>
	<td bgcolor="#46a546"> </td>
	<td bgcolor="#9d261d"> </td>
	<td bgcolor="#9d261d"> </td>
	</tr>
	<tr>
	<td align="center">1.1 </td>
	<td bgcolor="#ffffff"> </td>
	<td bgcolor="#ffffff"> </td>
	<td bgcolor="#ffffff"> </td>
	<td bgcolor="#ffffff"> </td>
	<td bgcolor="#46a546"> </td>
	<td bgcolor="#46a546"> </td>
	<td bgcolor="#46a546"> </td>
	<td bgcolor="#46a546"> </td>
	<td bgcolor="#46a546"> </td>
	<td bgcolor="#9d261d"> </td>
	<td bgcolor="#9d261d"> </td>
	</tr>
	<tr>
	<td align="center">1.0 </td>
	<td bgcolor="#ffffff"> </td>
	<td bgcolor="#ffffff"> </td>
	<td bgcolor="#ffffff"> </td>
	<td bgcolor="#ffffff"> </td>
	<td bgcolor="#ffffff"> </td>
	<td bgcolor="#ffffff"> </td>
	<td bgcolor="#46a546"> </td>
	<td bgcolor="#46a546"> </td>
	<td bgcolor="#46a546"> </td>
	<td bgcolor="#46a546"> </td>
	<td bgcolor="#9d261d"> </td>
	</tr>
	</table>
	<p>An empty cell indicates that the compatibility hasn't been tested for a particular combination.</p>
	<h3 id="User_Interface_Breakdown">User Interface Breakdown</h3>
	<p>The main points of interest are highlighted in the following picture :</p>
	<p>
	<img align="middle" title="EMF Compare's basic user interface" alt="EMF Compare's basic user interface" border="0" src="./../images/EMF_Compare_User_Interface.png"/>
	</p>
	<ol>
	<li>Overview of the differences detected between the given two (or three) models.</li>
	<li>First version of the compared models.</li>
	<li>Second version of the compared models.</li>
	<li>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.</li>
	<li>When you select a difference in the top panel, the consequences of the merge of this difference are highlighted in green and red.
	<ul>
	<li>The consequences highlighted in <span style="color:green">green</span> are the differences that will be merge with the selected difference.</li>
	<li>The consequences highlighted in <span style="color:red">red</span> are the differences that will be not "mergeable" after the merge of the selected difference.</li>
	<li>A click on a <span style="color:green">green</span> or <span style="color:red">red</span> rectangle in the right gutter will lead you to the concerned consequence.</li>
	</ul>
	</li>
	</ol>
	<h4 id="Toolbar">Toolbar</h4>
	<p>The toolbar displays the current status of the comparison and allows you to act on differences.</p>
	<p>
	<img align="middle" title="EMF Compare's user interface toolbar" alt="EMF Compare's user interface toolbar" border="0" src="./../images/EMF_Compare_User_Interface_Toolbar.png"/>
	</p>
	<ol>
	<li>Gives the number of differences still to be merged, and the number of differences filtered from the view.</li>
	<li>Allows to change the direction of consequences that are highlighted in green and red in the top panel. You can either display the consequences of a merge from left to right or right to left.</li>
	<li>Allows you to merge the single, currently selected difference in a given direction (left to right, or right to left).</li>
	<li>Allows you to merge all non conflicting differences (left to right, or right to left) at once.</li>
	<li>Allows you to navigate through the detected differences.</li>
	<li>Allows to expand/collapse all differences in the top panel.</li>
	<li>This button will allow you to group differences together in the structural view. For example, grouping all "Additions" or "Deletions" together.</li>
	<li>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".</li>
	<li>Allows to save the comparison model.</li>
	</ol>
	<p>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, 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.</p>
	<p>
	<img align="middle" title="EMF Compare's user interface toolbar" alt="EMF Compare's user interface toolbar" border="0" src="./../images/EMF_Compare_User_Interface_Toolbar_With_Read_Only_Side.png"/>
	</p>
	<ol>
	<li>Allows to change the kind of consequences that are highlighted in green and red in the top panel. You can either display the consequences of accepting/rejecting the selected change.</li>
	<li>Allows you to accept the single, currently selected change.</li>
	<li>Allows you to reject the single, currently selected change.</li>
	<li>Allows you to accept all non conflicting changes at once.</li>
	<li>Allows you to reject all non conflicting changes at once.</li>
	</ol>
	<h4 id="Signification_of_icons_associated_with_differences">Signification of icons associated with differences</h4>
	<p>When you run a comparison involving two models (a 2-way comparison), the icons associated with differences are:</p>
	<ul>
	<li>
	<img title="Addition" alt="Addition" border="0" src="./../images/add_ov.gif"/> represent an addition in the left side model of the comparison.
	</li>
	<li>
	<img title="Deletion" alt="Deletion" border="0" src="./../images/del_ov.gif"/> represent a deletion in the left side model of the comparison.
	</li>
	<li>
	<img title="Change" alt="Change" border="0" src="./../images/chg_ov.gif"/> represent a change (set/unset/move) in the left side model of the comparison.
	</li>
	</ul>
	<p>When you run a comparison involving three models (a 3-way comparison), the icons associated with differences are:</p>
	<ul>
	<li>
	<img title="Incoming change" alt="Incoming change" border="0" src="./../images/r_inchg_ov.gif"/> incoming differences are changes that were made in the right-side/remote model since common ancestor.
	</li>
	<li>
	<img title="Outgoing change" alt="Outgoing change" border="0" src="./../images/r_outchg_ov.gif"/> outgoing differences are changes that were made in the left-side/local model since common ancestor.
	</li>
	<li>
	<img title="Incoming addition" alt="Incoming addition" border="0" src="./../images/r_inadd_ov.gif"/> represent an incoming addition difference.
	</li>
	<li>
	<img title="Incoming deletion" alt="Incoming deletion" border="0" src="./../images/r_indel_ov.gif"/> represent an incoming deletion difference.
	</li>
	<li>
	<img title="Outgoing addition" alt="Outgoing addition" border="0" src="./../images/r_outadd_ov.gif"/> represent an outgoing addition difference.
	</li>
	<li>
	<img title="Outgoing deletion" alt="Outgoing deletion" border="0" src="./../images/r_outdel_ov.gif"/> represent an outgoing deletion difference.
	</li>
	<li>
	<img title="Incoming conflict" alt="Incoming conflict" border="0" src="./../images/confr_chg_ov.gif"/> 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.
	</li>
	<li>
	<img title="Outgoing conflict" alt="Outgoing conflict" border="0" src="./../images/confchg_ov.gif"/> 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.
	</li>
	<li>
	<img title="Incoming conflict addition" alt="Incoming conflict addition" border="0" src="./../images/confr_add_ov.gif"/> represent an incoming addition conflict.
	</li>
	<li>
	<img title="Incoming conflict deletion" alt="Incoming conflict deletion" border="0" src="./../images/confr_del_ov.gif"/> represent an incoming deletion conflict.
	</li>
	<li>
	<img title="Outgoing conflict addition" alt="Outgoing conflict addition" border="0" src="./../images/confadd_ov.gif"/> represent an outgoing addition conflict.
	</li>
	<li>
	<img title="Outgoing conflict deletion" alt="Outgoing conflict deletion" border="0" src="./../images/confdel_ov.gif"/> represent an outgoing deletion conflict.
	</li>
	<li>
	<img title="Incoming pseudo conflict" alt="Incoming pseudo conflict" border="0" src="./../images/pconfr_chg_ov.gif"/> 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.
	</li>
	<li>
	<img title="Outgoing pseudo conflict" alt="Outgoing pseudo conflict" border="0" src="./../images/pconfchg_ov.gif"/> 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.
	</li>
	<li>
	<img title="Incoming pseudo conflict addition" alt="Incoming pseudo conflict addition" border="0" src="./../images/pconfr_add_ov.gif"/> represent an incoming pseudo conflict addition.
	</li>
	<li>
	<img title="Incoming pseudo conflict deletion" alt="Incoming pseudo conflict deletion" border="0" src="./../images/pconfr_del_ov.gif"/> represent an incoming pseudo conflict deletion.
	</li>
	<li>
	<img title="Outgoing pseudo conflict addition" alt="Outgoing pseudo conflict addition" border="0" src="./../images/pconfadd_ov.gif"/> represent an outgoing pseudo conflict addition.
	</li>
	<li>
	<img title="Outgoing pseudo conflict deletion" alt="Outgoing pseudo conflict deletion" border="0" src="./../images/pconfdel_ov.gif"/> represent an outgoing pseudo conflict deletion.
	</li>
	</ul>
	<h4 id="After_merge">After merge</h4>
	<p>The
	<i>merged</i> differences are displayed in <span style="color:gray">gray</span> and have a distinct icon.
	</p>
	<ul>
	<li>
	<img title="Merged difference from right to left" alt="Merged difference from right to left" border="0" src="./../images/merged_left_ov.gif"/> represent a difference that has been merged from right to left.
	</li>
	<li>
	<img title="Merged difference from left to right" alt="Merged difference from left to right" border="0" src="./../images/merged_right_ov.gif"/> represent a difference that has been merged from left to right.
	</li>
	</ul>
	<p>When you compare models with one in a read-only mode, the icons are:</p>
	<ul>
	<li>
	<img title="Accepted change" alt="Accepted change" border="0" src="./../images/merged_ov.gif"/> represent a change that has been accepted.
	</li>
	<li>
	<img title="Rejected change" alt="Rejected change" border="0" src="./../images/removed_ov.gif"/> represent a change that has been rejected.
	</li>
	</ul>
	<h4 id="Items_for_not_loaded_fragments">Items for not loaded fragments</h4>
	<p>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.</p>
	<p>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.</p>
	<p>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.</p>
	<table border="1" cellpadding="5" cellspacing="0">
	<tr>
	<th align="center">Before</th>
	<th align="center">After</th>
	</tr>
	<tr>
	<td>
	<img width="650" align="middle" border="0" src="./../images/EMF_Compare_NotLoadedItems_1.png"/>
	</td>
	<td>
	<img width="650" align="middle" border="0" src="./../images/EMF_Compare_NotLoadedItems_2.png"/>
	</td>
	</tr>
	</table>
	<h2 id="Launch_Comparison">Launch Comparison</h2>
	<p>Once installed, you can compare your files (locally or from any Version Control System) as usual using the
	<b>Compare With</b> menu.
	</p>
	<h3 id="Compare_with_local_models">Compare with local models</h3>
	<h4 id="Compare_with_each_other">Compare with each other</h4>
	<p>You can compare two or three models by selecting them and then using the
	<b>Compare With > Each Other</b> menu:
	</p>
	<p>
	<img align="middle" border="0" src="./../images/EMF_Compare_With_Each_Other.png"/>
	</p>
	<p>If you run a 3-way comparison (with 3 models), you have to select the ancestor of the comparison:</p>
	<p>
	<img align="middle" border="0" src="./../images/EMF_Compare_Select_Common_Ancestor.png"/>
	</p>
	<h4 id="Compare_with_local_history">Compare with local history</h4>
	<p>You can also compare your local model with one of its previous version available in the local history. For that, use the
	<b>Compare With > Local History</b> menu:
	</p>
	<p>
	<img align="middle" border="0" src="./../images/EMFC_Compare_With.png"/>
	</p>
	<h3 id="Compare_with_remote_models_.28EGit.29">Compare with remote models (EGit)</h3>
	<p>The following displays the important part of a model life cycle with regards to the comparison. The full life cycle can be followed on
	<a href="./sample-use-case.html" title="./sample-use-case.html">Sample Use Case</a>
	</p>
	<h4 id="Compare_with_latest">Compare with latest</h4>
	<p>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.</p>
	<p>The name of our sample project will be "library". It contains a single folder "model" containing two models :</p>
	<ul>
	<li>library_Types.uml will contain our primitive types,</li>
	<li>library.uml will contain our actual model.</li>
	</ul>
	<p>The model itself is a very simple library. Graphically speaking :</p>
	<p>
	<img border="0" src="./../images/EMF_Compare_Use_Model.png"/>
	</p>
	<p>We commit this initial file as the original model. We then slightly modify it so that it now looks like :</p>
	<p>
	<img border="0" src="./../images/EMF_Compare_Use_Model_Changed.png"/>
	</p>
	<p>But how do we know exactly what changed? Let's compare this with the file from the Git Index :</p>
	<p>
	<img border="0" src="./../images/EMF_Compare_Use_Compare_1.png"/>
	</p>
	<p>This will open a comparison editor. Let's select one of the differences displayed on its top half :</p>
	<p>
	<img border="0" src="./../images/EMF_Compare_Use_Compare_3.png"/>
	</p>
	<ol>
	<li>We've selected the difference corresponding to the addition of attribute
	<b>alias</b> in the class
	<b>Writer</b>. A double-click on this difference updated our two panes below.
	</li>
	<li>
	<b>alias</b> has been added to the properties of Class
	<b>Writer</b>. In the model, this corresponds to a change to the reference
	<i>ownedAttributes</i> of the
	<i>Writer</i> Class. This sub-panel indicates the actual reference that was changed in oder to remind us of the context.
	</li>
	<li>This displays all values of the reference outlined in (2) as they are in the
	<i>left</i> model. This is where we see the new value,
	<b>alias</b> outlined.
	</li>
	<li>As for (2), this will display the context of the selected difference. The same reference will usually be displayed in both (2) and (4).</li>
	<li>This panel displays all values of the reference outlined in (4) as they are in the
	<i>right</i> model. In here, we see the location of
	<b>alias</b> outlined as an empty space. This rectangle is where the new value will be added if we merge it.
	</li>
	</ol>
	<p>In this case, it is possible to merge towards the
	<i>right</i> : the
	<i>index</i> version of the model is editable, like any other file in the index. If we merge this difference towards the
	<i>right</i>, then it will exist an
	<i>unstaged</i> version of the model, and a
	<i>staged</i> version of the model, that will include the merged difference.
	</p>
	<p>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
	<i>master</i> branch.
	</p>
	<h4 id="Compare_two_differing_branches">Compare two differing branches</h4>
	<p>After that, our model can evolve, and evolve separately in multiple branches. Let's consider the case where we would have a
	<i>master</i> branch differing from a
	<i>borrowables</i> branch such as the two look like this (the branching point was the model we've already displayed above) :
	</p>
	<table border="1" cellpadding="5" cellspacing="0">
	<tr>
	<th align="center">Master</th>
	<th align="center">Borrowables</th>
	</tr>
	<tr>
	<td>
	<img align="middle" border="0" src="./../images/EMF_Compare_Use_Compare_Master.png"/>
	</td>
	<td>
	<img align="middle" border="0" src="./../images/EMF_Compare_Use_Compare_5.png"/>
	</td>
	</tr>
	</table>
	<p>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
	<i>Compare With > Branch, Tag or Reference</i> action :
	</p>
	<p>
	<img align="middle" border="0" src="./../images/EMF_Compare_Use_Compare_With_Master_1.png"/>
	</p>
	<p>and compare with master :</p>
	<p>
	<img align="middle" border="0" src="./../images/EMF_Compare_Use_Compare_With_Master_2.png"/>
	</p>
	<p>This shows us all differences between our local copy and the master branch that were made since the 'branching' point.</p>
	<p>
	<img align="middle" border="0" src="./../images/EMF_Compare_Merge.png"/>
	</p>
	<p>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.
	<b>Regular</b> 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
	<b>incoming</b> differences, decorated with a blue arrow (
	<img border="0" src="./../images/EMF_Compare_Incoming_Change.gif"/>) or a derived icon, and
	<b>outgoing</b> differences decorated with a gray arrow (
	<img border="0" src="./../images/EMF_Compare_Outgoing_Change.gif"/>) or a derived icon.
	</p>
	<p>
	<b>Incoming</b> differences are changes that were made in the remote branch (here,
	<i>master</i>) since the branching point (common ancestor).

	<b>Outgoing</b> differences are changes that were made in the local copy (here, the
	<i>borrowables</i> branch) since the branching point.
	</p>
	<p>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.</p>
	<p>The interface also lets you display the common ancestor of both models through the
	<img border="0" src="./../images/EMF_Compare_Ancestor.gif"/> icon. For example, if we select the
	<b>Book</b> class, we can see how it looks like on all three versions :
	</p>
	<p>
	<img align="middle" border="0" src="./../images/EMF_Compare_Merge_Book_Ancestor.png"/>
	</p>
	<p>You can navigate through the differences using the appropriate actions, either the previous (
	<img border="0" src="./../images/EMF_Compare_Prev_Diff.gif"/>) or the next (
	<img border="0" src="./../images/EMF_Compare_Next_Diff.gif"/>) difference.
	</p>
	<p>The remaining two actions are those that actually interest us here we can either accept all non-conflicting differences to the local copy through
	<img border="0" src="./../images/accept_all_changes.gif"/> or accept them one after the other through
	<img border="0" src="./../images/accept_change.gif"/>.
	</p>
	<p>Accept
	<b>all</b> 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
	<i>master</i>, the right side). We will then select all
	<i>incoming</i> differences (under the
	<i>Right side</i> node) one after the other and merge them one by one. This gives us our merged model :
	</p>
	<p>
	<img align="middle" border="0" src="./../images/EMF_Compare_Merged.png"/>
	</p>
	<h4 id="Resource_name_changes">Resource name changes</h4>
	<p>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.</p>
	<p>
	<img align="middle" border="0" src="./../images/EMF_Compare_ResourceNameChange.png"/>
	</p>
	<h2 id="Customization">Customization</h2>
	<h3 id="Engines">Engines</h3>
	<p>During each comparison EMF Compare uses several engines (see
	<a href="./../developer/developer-guide.html#Comparison_Process" title="./../developer/developer-guide.html#Comparison_Process">Comparison process</a>)
	</p>
	<ul>
	<li>Match engine </li>
	<li>Difference engine</li>
	<li>Equivalence engine</li>
	<li>Requirement engine</li>
	<li>Conflict detector</li>
	</ul>
	<p>EMF Compare offers a way to configure those engines.</p>
	<h4 id="Match_Engine">Match Engine</h4>
	<p>To customize matching phase go to the "Engines" preference page.</p>
	<ul>
	<li>Open preferences: Window > Preferences > EMF Compare</li>
	<li>Select "Engines" page</li>
	<li>Open Match tab</li>
	</ul>
	<p>
	<img border="0" src="../images/EMF_Compare_Match_Engine_Preference_Page.png"/>
	</p>
	<h5 id="Configure_registered_matching_engine">Configure registered matching engine</h5>
	<p>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.</p>
	<h6 id="Matching_strategy_for_default_match_engine">Matching strategy for default match engine</h6>
	<p>The matching strategy of the default match engine can be configured.</p>
	<p>
	<img border="0" src="../images/EMF_Compare_Match_Engine_Preference_Page_Configuration.png"/>
	</p>
	<p>Basically, you can choose to use either a strategy based on object identifiers or a strategy based on object content or both.</p>
	<ul>
	<li>Only: Matching strategy based on id only. The match engine will only match two objects together if they have the same identifier. (see
	<a href="./../developer/developer-guide.html#Match_2" title="./../developer/developer-guide.html#Match_2">Identifiers in Default Match Engine</a>).
	</li>
	<li>Never: Matching strategy based on object content. Only the structure of the object will define if two objects can match.</li>
	<li>When available: This strategy will use both of the above strategies. If an identifier is found on an object then it will use the "Identifier Strategy" if not it will use the "Content strategy".</li>
	</ul>
	<h5 id="Enable.2FDisable_Match_Engines">Enable/Disable Match Engines</h5>
	<p>Additional Match Engines can be contributed through EMF Compare's extension point (see
	<a href="./../developer/developer-guide.html#Overriding_the_Match_engine" title="./../developer/developer-guide.html#Overriding_the_Match_engine">Override Match Engine</a>). They can be enabled or disabled from the preference page.
	</p>
	<p>
	<img border="0" src="../images/EMF_Compare_Match_Engine_Preference_Page_List.png"/>
	</p>
	<ul>
	<li>On this page you will find all registered match engines. They are ordered by priority (highest priority on top of the list). To enable an engine, check it. Uncheck the engine to disabled it. The first enabled Match engine that handles the comparison will be used.</li>
	</ul>
	<h4 id="For_other_engines">For other engines</h4>
	<p>To customize one of the other phase, go to the "Engines" preference page.</p>
	<ul>
	<li>Open preferences: Window > Preferences > EMF Compare</li>
	<li>Select "Engines" page</li>
	<li>Open the tab corresponding to the phase to customize.</li>
	</ul>
	<p>
	<img border="0" src="../images/EMF_Compare_Engines_Preference_Page.png"/>
	</p>
	<h5 id="Choose_the_default_engine">Choose the default engine</h5>
	<p>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.</p>
	<h3 id="Post_processors_customization">Post processors customization</h3>
	<p>Result of each phase of the comparison process (see
	<a href="./../developer/developer-guide.html#Comparison_Process" title="./../developer/developer-guide.html#Comparison_Process">Comparison process</a>) can be refined thanks to post processors.
	</p>
	<p>More information:</p>
	<ul>
	<li>
	<a href="./../developer/developer-guide.html#Refine_the_default_Match_result" title="./../developer/developer-guide.html#Refine_the_default_Match_result">Refine Match Result</a>,
	</li>
	<li>
	<a href="./../developer/developer-guide.html#Refine_the_default_Diff_result" title="./../developer/developer-guide.html#Refine_the_default_Diff_result">Refine Diff Result</a>,
	</li>
	<li>
	<a href="./../developer/developer-guide.html#Refine_the_default_equivalences" title="./../developer/developer-guide.html#Refine_the_default_equivalences">Refine Equivalence Result</a>
	</li>
	<li>etc ...</li>
	</ul>
	<p>To customize those post-processors go to the related preference page. </p>
	<ul>
	<li>Open preference page: Open Window > Preferences </li>
	<li>Select post-processors preference page: Select EMF Compare > Post Processors</li>
	</ul>
	<p>
	<img border="0" src="../images/EMF_Compare_Post_Processor_Preference_Page.png"/>
	</p>
	<p>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.</p>
	<h4 id="Model_Resolvers">Model Resolvers</h4>
	<p>For each comparison, EMF Compare needs to define which resources are about to be compared. This scope is called the logical model (see
	<a href="./../developer/logical-model.html#What_is_a_logical_model_.3F" title="./../developer/logical-model.html#What_is_a_logical_model_.3F">Logical Model</a>). 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.
	</p>
	<p>To customize the model resolution behavior go to the "Resolution strategy" preference page.</p>
	<ol>
	<li>Open preferences: Window -> Preferences</li>
	<li>Open "Resolution strategy" preference page: EMF Compare > Resolution strategy</li>
	</ol>
	<p>
	<img border="0" src="../images/EMF_Compare_Model_Resolver_Preference_Page.png"/>
	</p>
	<h5 id="Choose_a_strategy">Choose a strategy</h5>
	<p>EMF Compare proposes different strategies:</p>
	<ul>
	<li>Workspace: Search for cross-references to (and from) the compared resource within all models from the workspace.
	<b>This strategy is highly recommended in case of a comparison with remote models (EGit).</b>
	</li>
	<li>Project: Search for cross-references to (and from) the compared resource within all models from its containing project.</li>
	<li>Container: Search for cross-references to (and from) the compared resource within all models from the same container.</li>
	<li>Outgoing: Only search for cross-references from the compared resource to its children (and recursively).</li>
	</ul>
	<p>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.</p>
	<h5 id="Disable_model_resolution">Disable model resolution</h5>
	<p>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".</p>
	<h3 id="User_Interface_customization">User Interface customization</h3>
	<h4 id="Colors_Customization">Colors Customization</h4>
	<p>You can customize the colors used by EMF Compare to highlight differences in the user interface.</p>
	<ol>
	<li>Open preferences: Window -> Preferences</li>
	<li>Go to Colors and Fonts preferences: Select -> General -> Appearance -> Colors and Fonts</li>
	<li>Open the EMF Compare Category.</li>
	<li>Select the color you want to customize and click and edit to pick a new color. Your editor will now use your new colors.</li>
	</ol>
	<p>
	<img border="0" src="./../images/EMFCompare_ColorPreferences.png"/>
	</p>
	<h4 id="Filters">Filters</h4>
	<p>You have already been explained how to use filters to hide or display differences in EMF Compare UI (see
	<a href="#Toolbar">Toolbar</a>). This chapter teaches you how to customize filter default activation.
	</p>
	<p>First open the filters preference page:</p>
	<ul>
	<li>Open preferences: Window > Preferences > EMF Compare</li>
	<li>Select "Filters" page.</li>
	</ul>
	<p>
	<img border="0" src="../images/EMF_Compare_Filters_Preference_Page.png"/>
	</p>
	<p>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
	<a href="./../developer/developer-guide.html#Add_your_own_filter" title="./../developer/developer-guide.html#Add_your_own_filter">Add you own filter</a>).
	</p>
	<p>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:</p>
	<ul>
	<li>Always: Each time you will modify the filters selection in UI, the selected set of filters will be synchronized with the preferences. This way the filters that you have selected will be kept between comparisons.</li>
	<li>Never: The selection of filters in UI will never be synchronized with the preferences.</li>
	<li>Prompt: You will be asked each time that filters selection is modified if you want to synchronize the new set of filters with the preferences. If this option is set, a popup will appear just after each filter activation or deactivation. This popup proposes several ways to handle the newly selected set of filters:
	<img border="0" src="../images/EMF_Compare_Filters_Synchronization_Dialog.png"/>
	<ul>
	<li>If your answer is "Yes", the current set of selected filters will be synchronized with the preferences. In other word, it will become your default activated set of filters.</li>
	<li>If your answer is "No", nothing will be synchronized. Next time you will launch a comparison, the activated filters will be defined by the preferences.</li>
	<li>If you check "Do not ask me again", the above behaviors will be executed and the synchronization behavior will change. It will be set to "Always" if you have selected "Yes". It will be set to "Never" if you have selected "No".</li>
	</ul>
	</li>
	</ul>
	<h4 id="Groups">Groups</h4>
	<p>You have already been explained how to use groups to gather differences in EMF Compare UI (see
	<a href="#Toolbar">Toolbar</a>). This chapter teaches you how to customize the default activated group in EMF Compare.
	</p>
	<p>First open the Groups preference page:</p>
	<ul>
	<li>Open preferences: Window > Preferences > EMF Compare</li>
	<li>Select "Groups" page.</li>
	</ul>
	<p>
	<img border="0" src="../images/EMF_Compare_Groups_Preference_Page.png"/>
	</p>
	<p>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:</p>
	<p>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.</p>
	<p>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: </p>
	<ul>
	<li>Always: Each time you will select a group in UI, it will become the default group.</li>
	<li>Never: The selection of a group in UI will never modify the default group.</li>
	<li>Prompt: You will be asked each time you change the active group if you want to synchronize it with the preferences. A popup will appear. It will propose several ways to handle the newly selected group:
	<img border="0" src="../images/EMF_Compare_Groups_Synchronization_Dialog.png"/>
	<ul>
	<li>If your answer is "Yes", the current group will be synchronized with the preferences. In other word, it will become the default group.</li>
	<li>If your answer is "No", nothing will be synchronized. Next time you will start a comparison, the default group will be defined by the preferences.</li>
	<li>If you check "Do not ask me again", the above behaviors will be executed and the synchronization behavior will change. It will be set to "Always" if you have selected "Yes". It will be set to "Never" if you have selected "No".</li>
	</ul>
	</li>
	</ul>
	<h4 id="Items_providers">Items providers</h4>
	<p>In EMF item providers are used to define how elements are displayed (label, icon etc..). They belong to the
	<a href="http://help.eclipse.org/kepler/index.jsp?topic=%2Forg.eclipse.emf.doc%2Freferences%2Foverview%2FEMF.Edit.html">EMF.Edit</a> 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".
	</p>
	<p>
	<img border="0" src="../images/Item_Providers_Preference_Page.png"/>
	</p>
	<p>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.</p>
	<h2 id="Features">Features</h2>
	<h3 id="Grouping_Differences">Grouping Differences</h3>
	<p>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 :</p>
	<p>
	<img border="0" src="./../images/EMF_Compare_Groups_Choice.png"/>
	</p>
	<dl>
	<dt>Default</dt>
	<dd>Do not try and group differences together, display them as they were detected.</dd>
	</dl>
	<p>
	<img border="0" src="./../images/EMF_Compare_Groups_Default.png"/>
	</p>
	<dl>
	<dt>By Kind</dt>
	<dd>Group differences by their kind (
	<i>additions</i>,
	<i>deletions</i>,
	<i>moves</i>,
	<i>changes</i>).
	</dd>
	</dl>
	<p>
	<img border="0" src="./../images/EMF_Compare_Groups_Kind.png"/>
	</p>
	<dl>
	<dt>By Side</dt>
	<dd>Group differences according to their side: left or right and a special group regrouping differences in conflicts with other differences together. This grouping strategy is display by default in case of a 3-way comparison.</dd>
	</dl>
	<p>
	<img border="0" src="./../images/EMF_Compare_Groups_Side.png"/>
	</p>
	<dl>
	<dt>By Resource</dt>
	<dd>Group differences according to their resource: useful when more than two resources involved in comparison and/or resources are split into fragments. </dd>
	</dl>
	<p>
	<img border="0" src="./../images/EMF_Compare_Groups_Resource.png"/>
	</p>
	<p>PENDING UPDATE, this is a demo displaying EMF Compare 1.3
	<a href="http://www.eclipse.org/emf/compare/doc/features/videos/Groups/groups.htm">Demo</a>
	</p>
	<p>New grouping strategies can be provided to EMF Compare through extension points. See
	<a href="./../developer/developer-guide.html#Add_your_own_group" title="./../developer/developer-guide.html#Add your own group">Add your own group</a> section in developer guide for further details.
	</p>
	<h3 id="Filtering_Differences">Filtering Differences</h3>
	<p>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 :</p>
	<p>
	<img border="0" src="./../images/EMF_Compare_Filters_Choice.png"/>
	</p>
	<dl>
	<dt>Empty Resource Mappings</dt>
	<dd>Filter out all resource mappings with no differences from the view. Enabled by default.</dd>
	<dt>Feature Map differences</dt>
	<dd>Filters out differences that apply on EFEatureMapEntry type.</dd>
	<dt>Pseudo conflicts differences</dt>
	<dd>Filter out all pseudo conflicts differences (only in case of a 3-way comparison). Enabled by default.</dd>
	<dt>Identical elements</dt>
	<dd>Filter out all identical elements (elements with no differences). Enabled by default.</dd>
	<dt>Cascading differences</dt>
	<dd>Filter out all differences that are contained under differences (except when in conflict). Enabled by default.</dd>
	</dl>
	<p>PENDING UPDATE, this is a demo displaying EMF Compare 1.3
	<a href="http://www.eclipse.org/emf/compare/doc/features/videos/Filters/filters.htm">Demo</a>
	</p>
	<p>New filters can be provided to EMF Compare through extension points. See
	<a href="./../developer/developer-guide.html#Add_your_own_filter" title="./../developer/developer-guide.html#Add your own filter">Add your own filter</a> section in developer guide for further details.
	</p>
	<h3 id="Handling_Conflicts">Handling Conflicts</h3>
	<p>When a 3-way comparison has conflicts, all differences involved in the same conflict are grouped under a Conflict node.</p>
	<p>In the following case, the Employee Green has his manager reference in conflict. The left side of the comparison shows that the manager of the Employee Green is the employee Smith while the right side side shows that the manager is the Employee Johnson.
	The consequences of a merge from right to left of the selected difference are displayed.</p>
	<p>When the left side difference
	<i>Employee Smith [ manager changed ]</i> is selected in the top panel, the right side difference
	<i>Employee Johnson [ manager changed ]</i> is highlighted in red, that means if the the left side difference
	<i>Employee Smith [ manager changed ]</i> is merged from right to left, then it will be impossible to merge the right side difference
	<i>Employee Johnson [ manager changed ]</i> from left to right.
	</p>
	<p>
	<img border="0" src="./../images/EMF_Compare_Handling_Conflict_1.png"/>
	</p>
	<p>After the merge of the left side difference from right to left
	<i>Employee Smith [ manager changed ]</i>, the right side difference
	<i>Employee Johnson [ manager changed ]</i> is not "mergeable" from left to right anymore, it has been merged from right to left automatically.
	</p>
	<p>
	<img border="0" src="./../images/EMF_Compare_Handling_Conflict_2.png"/>
	</p>
	<h3 id="Text_Attribute_Comparison">Text Attribute Comparison</h3>
	<p>In case of differences made on
	<i>String</i>-typed attributes, specifics actions are available in the top-right of the content viewer panel.
	</p>
	<p>
	<img border="0" src="./../images/EMF_Compare_Text_Compare.png"/>
	</p>
	<ol>
	<li>Allows to merge all changes of the current difference.</li>
	<li>Allows to merge the current change.</li>
	<li>Allows to move to the next/previous textual difference (in case of multi-valuated
	<i>String</i>-typed attributes).
	</li>
	<li>Allows to move to next/previous change in the current textual difference.</li>
	</ol>
	<p>PENDING UPDATE, this demo displays EMF Compare 1.3

	<a href="http://www.eclipse.org/emf/compare/doc/features/videos/Text%20compare/textCompare.htm">Demo</a>
	</p>
	<h3 id="Graphical_Comparison">Graphical Comparison</h3>
	<p>EMF compare provides the ability to compare models with Papyrus graphical modeler (GMF Diagrams). To get the graphical comparison, the
	<i>EMF Compare Papyrus integration</i> feature and Papyrus have to be installed.
	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 <span style="color:blue">incoming</span> and <span style="color:gray">outgoing</span> changes, and <span style="color:red">conflicts</span>. To put in relief the graphical differences, some decorators are used:
	</p>
	<ul>
	<li>On one hand, to focus on the impacted objects, identifying them with markers. These markers are simple transparent rectangles which are set down above the concerned objects and are lightly larger.</li>
	<li>On the other hand, through phantoms (place-holders), to locate either the place where objects were deleted or the target location where objects should be added after merging.</li>
	</ul>
	<p>The color of the concerned decorators are highlighted on selection of the difference.</p>
	<p>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.</p>
	<p>
	<img border="0" src="./../images/EMF_Compare_Graphical_AddClassA.png"/>
	</p>
	<p>About phantoms (place-holders):</p>
	<p>To ease their readability, in some cases, their context have to be displayed:</p>
	<ul>
	<li>If they are nested in an other phantom (e.g. due to a delete of the parent object), this last contextual one is displayed at the same time as the main phantom concerned by the current selected change.</li>
	<li>If they are edges connected to deleted nodes or edges, these last contextual ones are displayed at the same time as the main edge phantom.</li>
	<li>The color of the contextual phantoms (dependencies) is not highlighted.</li>
	</ul>
	<p>They are drawn as:</p>
	<ul>
	<li>A simple rectangle for nodes, at the same origin location (and size).</li>
	<li>A simple line (with the same bend points) for edges, at the same location.</li>
	<li>A simple line for nodes as element of containment list. For this case, the same LCS computation will be used to locate in the list, at the good index.</li>
	<li>Particular cases: If the location of the contextual phantoms was changed, the new location of the main phantom is computed.
	<ul>
	<li>A node place-holder, related to a delete of a node, embedded in a node where the location changed.</li>
	<li>An edge place-holder between nodes where the location changed. In this case, the display of the line is drawn again.</li>
	</ul>
	</li>
	</ul>
	<p>Here is an example of nested phantom:</p>
	<ul>
	<li>the first capture represent an addition of a lifeline in sequence diagram.</li>
	</ul>
	<p>
	<img border="0" src="./../images/EMF_Compare_Graphical_Phantom.gif"/>
	</p>
	<ul>
	<li>the second capture represent an addition of an execution inside the lifeline. We can see the phantom of the execution element, which is highlighted and the phantom of the lifeline parent, which is not highlighted. </li>
	</ul>
	<p>
	<img border="0" src="./../images/EMF_Compare_Graphical_Nested_Phantom.gif"/>
	</p>
	<p>Have a look on the following demos :</p>
	<p>PENDING update videos</p>
	<p>
	<a href="http://www.eclipse.org/emf/compare/doc/features/videos/EcoreTools-v2/EMFCompareEcoreTools.html" title="http://www.eclipse.org/emf/compare/doc/features/videos/EcoreTools-v2/EMFCompareEcoreTools.html">Demo : Comparing Ecore files with diagrams</a>
	</p>
	<p>
	<a href="http://www.eclipse.org/emf/compare/doc/features/videos/Papyrus/EMFComparePapyrus.html" title="http://www.eclipse.org/emf/compare/doc/features/videos/Papyrus/EMFComparePapyrus.html">Demo : Comparing UML files with diagrams</a>
	</p>
	<h3 id="Logical_Model">Logical Model</h3>
	<p>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
	<i>control</i> 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
	<i>genmodel</i> file (that depends on its underlying
	<i>ecore</i> file) :
	</p>
	<p>
	<img border="0" src="./../images/EMF_Compare_Logical_Compare_Action.png"/>
	</p>
	<p>EMF Compare will actually consider both files when comparing :</p>
	<p>
	<img border="0" src="./../images/EMF_Compare_Logical_Compare_Result.png"/>
	</p>
	<p>PENDING UPDATE

	<a href="http://www.eclipse.org/emf/compare/doc/features/videos/LogicalModels/LogicalModels.html">Demo</a>
	</p>
	<h3 id="UML_Specialization">UML Specialization</h3>
	<p>A specific work has been done with EMF Compare for UML. It consists in an additional filter named
	<b>UML refined elements</b>. This filter is active by default when a comparison involves UML resources.
	</p>
	<p>
	<img border="0" src="./../images/EMF_Compare_UML_Filter.png"/>
	</p>
	<p>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:</p>
	<p>
	<img border="0" src="./../images/EMF_Compare_UML_Association.png"/>
	</p>
	<p>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.</p>
	<p>Here is the comparison of two UML model, one with an association (the left side), another without (the right side). The
	<b>UML refined elements</b> filter has been deactivated:
	</p>
	<p>
	<img border="0" src="./../images/EMF_Compare_UML_Association_2.png"/>
	</p>
	<p>We can see a lot of differences.
	The same comparison with the
	<b>UML refined elements</b> filter activated:
	</p>
	<p>
	<img border="0" src="./../images/EMF_Compare_UML_Association_3.png"/>
	</p>
	<p>PENDING</p>
	<p>
	<a href="http://www.eclipse.org/emf/compare/doc/features/videos/UML%20comparison/compareUml.htm" title="http://www.eclipse.org/emf/compare/doc/features/videos/UML%20comparison/compareUml.htm">Demo : Specific support to encapsulate profiles and stereotypes diffs</a>
	</p>
	<h2 id="Logical_Model_View">Logical Model View</h2>
	<p>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.</p>
	<p>For more details about the logical model, please visit the
	<a href="developer/logical-model.html">Logical model</a> page.
	</p>
	<p>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.</p>
	<p>The view is accessible from
	<i>Window > Show View > Other ... > EMF Compare > Logical Model View</i>.
	</p>
	<p>
	<img border="0" src="./../images/EMF_Compare_LogicalModelView_ShowView.png"/>
	</p>
	<p>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. </p>
	<p>
	<img border="0" src="./../images/EMF_Compare_LogicalModelView.png"/>
	</p>
	<p>While computing the logical model for a given model, the view shows the progression of computing.</p>
	<p>
	<img border="0" src="./../images/EMF_Compare_LogicalModelView_Computing.png"/>
	</p>
	<h3 id="Toolbar_2">Toolbar</h3>
	<p>
	<img border="0" src="./../images/EMF_Compare_LogicalModelView_Toolbar.png"/>
	</p>
	<p>1. The button
	<i>Link with Editor and Selection</i> synchronize the Logical Model View to the active editor or the selected element in the Package Explorer View.
	</p>
	<ul>
	<li>The editors taken into account to populate the View will be: EMF Compare's comparison models editor, Papyrus editors, and EMF Reflective Model editors.</li>
	<li>Any EMF model selected in the Package Explorer View will populate the View.</li>
	<li>This button will be disabled by default.</li>
	<li>When the Logical Model View is opened for the first time, the button is disabled, and
	<b>no model is displayed</b> in the view,
	<b>even if one is selected</b> in the Package/Project Explorer View or the active editor.
	</li>
	<li>When the button is enabled, the synchronization becomes active.</li>
	<li>When the button is disabled, the synchronization becomes inactive. The last logical model computed and displayed in the View will remains until the button was enabled again and a new editor be active or a model was selected, or else the View was closed.</li>
	</ul>
	<p>2. The button
	<i>View Menu</i>
	</p>
	<p>
	<img border="0" src="./../images/EMF_Compare_LogicalModelView_Toolbar_ViewMenu.png"/>
	</p>
	<ul>
	<li>Flat list presentation: all models contained in the logical model are displayed as a flat list. Each item is followed by his relative path to the workspace.</li>
	</ul>
	<p>
	<img border="0" src="./../images/EMF_Compare_LogicalModelView_List.png"/>
	</p>
	<ul>
	<li>Tree presentation: all models contained in the logical model are displayed as a tree, relative to the workspace.</li>
	</ul>
	<p>
	<img border="0" src="./../images/EMF_Compare_LogicalModelView_Tree.png"/>
	</p>
	<h3 id="Contextual_Menu">Contextual Menu</h3>
	<p>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...</p>
	<p>
	<img border="0" src="./../images/EMF_Compare_LogicalModelView_ContextMenu.png"/>
	</p>
	<h2 id="Known_Bugs_and_Limitations">Known Bugs and Limitations</h2>
	<h3 id="Project_names_and_location">Project names and location</h3>
	<p>
	<b>Project names should match their location</b>
	</p>
	<h4 id="Cause">Cause</h4>
	<p>If you need to compare models that:</p>
	<ul>
	<li>reference another model in the same project (or another project which also meets the following point), and</li>
	<li>are located in a project which name (as seen in their '.project' file) does not match their containing folder's name (case sensitive).</li>
	</ul>
	<p>Due to
	<a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=354801">Bug 354801</a>, 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
	<i>EcoreModels</i>, it
	<b>must</b> be contained in a folder named
	<i>EcoreModels</i>. Any other name, even if changing only the case, such as
	<i>ecoreModels</i>, will cause issues when comparing fragmented models (or any model which references another).
	</p>
	<p>Note that this only applies to comparisons launched from within Eclipse, which would trigger the opening of the EMF Compare user interface.</p>
	<h4 id="Observed_Symptoms">Observed Symptoms</h4>
	<p>Symptoms vary, but they often include a NullPointerException somewhere in EMFSynchronizationModel such as :</p>
	<pre>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)
	</pre>
	<h3 id="Models_out_of_the_workspace">Models out of the workspace</h3>
	<p>
	<b>The models should be imported within the workspace</b>
	</p>
	<h4 id="Cause_2">Cause</h4>
	<p>Trying to compare models that are not present in the current Eclipse workspace from either the
	<i>Git repositories</i> perspective, or from the
	<i>Git Staging</i> view.
	</p>
	<p>Note that this only applies to comparisons launched from within Eclipse, which would trigger the opening of the EMF Compare user interface.</p>
	<h4 id="Observed_Symptoms_2">Observed Symptoms</h4>
	<p>Symptoms are mostly the same here as they would be with the limitation mentioned above regarding project names, and they usually include the same NullPointerException:</p>
	<pre>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)
	</pre>
	<h2 id="Other_Materials">Other Materials</h2>
	<ul>
	<li>
	<a href="http://www.eclipse.org/emf/compare/doc/features/videos/index.html">Videos of 2011 new features</a>
	</li>
	</ul>
	<p>Part of
	<a href="../index.html">EMF Compare Documentation</a>
	</p>
	<p>Version 3.2.0.201505180755</p>
	</body>
	</html>