path: root/plugins/org.eclipse.emf.compare.doc/src/tutorial/tutorial.mediawiki

= EMF Compare tutorial =

The aim of this tutorial is to guide you through the basic mechanisms of EMF Compare. The first part of this tutorial will explain you how to set up your environment. The second will help you to have a better understanding of the main differences that EMF Compare detects. The third part will explain you how EGit can interoperate with EMF Compare to compare model from a git repository. 

== Installation == 
EMF Compare is part of the Eclipse release train. You will find all you need in the eclipse release update of your platform. You can also find newer version on [[http://www.eclipse.org/emf/compare/ | EMF Compare web site]] in the download section.

In order to install EMF Compare:
* Open the installation wizard : Help > "Install New Software..".
* Select the update site from which you want to install EMF Compare. In this example we are using the Luna eclipse release update site:
** http://download.eclipse.org/releases/luna
* Check the feature called "EMF Compare IDE UI".
[[Image:../images/EMF_Compare_Tuto_Install.png]]
* Click on next.
[[Image:../images/EMF_Compare_Tuto_Install2.png]]
* Click on next.
* Read and accept the terms of the license agreement.
[[Image:../images/EMF_Compare_Tuto_Install3.png]]
* Click on finish.
* Once the installation is finished click on "Yes" to restart your platform.

== Tutorial ==

=== Set up ===

==== Install custom ExtLibrary plugins ====

This tutorial is based on the well know ExtLibrary meta-model (available from the EMF examples). However for the needs of this tutorial we have customized those plugins. We have:
* Set up a XMI id serialization to create models in which each element will have a unique id. EMF Compare can compare both models with id and models without id. If no id are available in the model, EMF Compare uses a heuristic to define if two elements matches.
* Removed the extendedLibrary content type to explain you how to set it up in your platform.
* Added extra icons to make it look prettier

===== Imports the plugins =====

Those plugins are hosted in the [[http://git.eclipse.org/c/emfcompare/org.eclipse.emf.compare.git |EMF Compare repository]]. To import those plugins in your workspace you can follow the [[http://wiki.eclipse.org/EGit/User_Guide#Starting_from_existing_Git_Repositories | EGit tutorial]]. Here are the main steps:
* Clone EMF Compare repository using the following URL (see [[http://wiki.eclipse.org/EGit/User_Guide#Cloning_Remote_Repositories | Clone a repository]] for further information):
** http://git.eclipse.org/gitroot/emfcompare/org.eclipse.emf.compare.git 
* Import the required plugins into your workspace:
** Open the "Git Repositories" view (if not already opened): Window > "Show view" > "Other...".
** Select "Git Repositories".
**: [[Image:../images/EMF_Compare_Tutorial_Git_Repo_View.png]]
** Select your clone of EMF Compare repository.
** Open the contextual menu and click on "Imports Projects..."
**: [[Image:../images/EMF_Compare_Tuto_Import_Project_Wizard.png]]
** Select the "tutorial" folder and click on next.
**: [[Image:../images/EMF_Compare_Tuto_Import_Project_Wizard1.png]]
** Check that the 3 required plugins are checked:
***: [[Image:../images/EMF_Compare_Tuto_Import_Project_Wizard2.png]]
** Click on Finish.

In the end you should have your workspace looking like this:

[[Image:../images/EMF_Compare_Tuto_Workspace.png]]

===== Launch runtime platform =====

Now that you get all you need in your workspace, you need to create a runtime platform. A runtime platform is basically a new eclipse platform built upon your current platform with the new plugins of your workspace included. To do so:
* Select one of the plugin in your workspace.
* Click on the play button in the toolbar [[Image:../images/EMF_Compare_Tuto_Run_Button.png]]. If you do not have this button in the toolbar you might need to switch to the Java perspective.
* Select "Eclipse Application" and then click on OK.
*: [[Image:../images/EMF_Compare_Tuto_Runtime_Platform.png]]
* A new eclipse platform should start. This is your runtime platform.

'''All the following instructions should be done on the runtime platform.''' 

==== Associate EXTLibrary models with EMF Compare Content type ====

EMF Compare editor is based on Content types mechanism. Basically, EMF Compare will be used in a comparison if the Content type of the current resource is either one of the following type (or inherit from one of them):
* XMI content type
* Ecore content type
* EMF Compare content type
You can also use the "Content Types" preference page to associate your model files with EMF Compare content type.

This is the first step of this tutorial. To do so:
* Open the preference page : Window > Preferences.
* Select the "Content Types" preference page: General > Content Types.
* Select EMF Compare item.
* Click on the "Add..." button.
* Write the pattern matching all extlibrary files : "*.extlibrary".
* Click on OK.

[[Image:../images/Content_Types_Preference_Page.png]]

If you are using the basic EXTLibrary plugins (imported from examples) this step is not mandatory since a content type is already defined and it inherits from XMI content type. However those plugins do not generate ids so we do not recommend you to use them.

=== Tutorial ===

==== Context ====

If you have correctly followed the previous steps you should have the following environment:
* The custom ExtLibray meta-model installed in your runtime
* Associated the .extlibrary files with the EMF Compare content type
* Using EMF Compare default preferences

==== Compare with history (2-way comparison) ====

Now that everything is set up, we are going to go through all major differences that EMF Compare detects and handles. To do so we are going to create step by step a library model. Each time that you will modify your library we are going to compare it with a previous version to see how EMF Compare handles each difference.

===== Create a library model =====

First we need to create our library model. To do so:
* Create a project with the name "TutorialModel" for example.
* Create an extlibrary model:
** Click on: File > New > Other.
** Select EXTLibrary Model.
**: [[Image:../images/Create_Extlibrary_Model.png]]
** Click on next.
** Set its name to "TutorialModel.extlibrary" for example.
**: [[Image:../images/Create_Extlibrary_Model_Set_Name.png]]
** Click on next.
** Select a Library element as root.
**: [[Image:../images/Create_Extlibrary_Model_Root_Element.png]]
** Click on finish.
Your model is now open.

[[Image:../images/EMF_Compare_Tuto_Model_Creation.png]]

===== Create a new book =====

We are now going to fill your library with your first book.
* Select the library element in your opened editor (In this example TutorialModel.extlibrary).
* Open the contextual menu.
* Select "New Child" > "Book".
* Save your model.

[[Image:../images/EMF_Compare_Tuto_Book_Creation.png]]

====== Compare with previous version ======
Now that our library contains one book let's compare it with the previous state of our model:
* Select your model file in project explorer (or package explorer) view.
* Open the contextual menu.
* Select "Compare With" > "Local History...".
[[Image:../images/Compare_With_Local_History.png]]

The history view is now open.

[[Image:../images/Local_History_View.png]]

This view will display each state of the file that Eclipse has saved for you. Each time you will save your model a new entry will appear. The item written in bold is the current version of your file. In the first part of this tutorial you will have to compare the current version of your model with it's previous version.

To do so, double click on the entry just bellow the bold entry.

The EMF Compare editor is now open.
 
[[Image:../images/EMF_Compare_Editor_Tuto_New_Book.png]]

This comparison is a 2-way comparison. That is to say the comparison is only between 2 inputs (the current version of your file and the previous version from your local history). You will see in the second part of this tutorial that there is also a 3-way comparison.

Let's have a look at the user interface. The tool bar look like this:

[[Image:../images/EMF_Compare_Tuto_Accept_Reject_Toolbar.png]]

This toolbar appears when you are in accept/reject mode. This mode is activated when at least one of the input is not writable. In our example the current version of your file can be modified whereas the previous version of it can not (since it provided by the local history). In this mode you can accept or reject a difference. This is obvious but the only resource that is going to be modified is the current version of your model.

The top of the editor is filled with the "Structure Merge viewer". In it, you will find a structured representation of all differences that EMF Compare has found.

On the bottom of the editor you have a viewer called "Content viewer". This viewer displays the content of your input models. On the left, it displays the content of the current version of your model. On the right it displays the content of the previous version.

To have a full understanding of the user interface please see [[./../user/user-guide.html#User_Interface_Breakdown|User Interface Breakdown]].

Now let's have a look to the difference: [[Image:../images/EMF_Compare_Tuto_New_Book_Difference.png]]

On this difference you find some pieces of information:
* The "+" overlay icon indicates that the difference is an addition (see [[./../user/user-guide.html#Signification_of_icons_associated_with_differences | Signification of icons associated with differences]] for further information).
* The enclosed suffix in brackets describes the nature of the difference and the name of feature which has been modified. In this case, the difference is an addition in the feature "Stock" (The modified feature is not "books" since it is derived feature. It is computed from the "real" feature "stock").

'''In this tutorial, you should never save the EMF Compare editor except if it is explicitly asked. For the moment, EMF Compare does not allow undoing an action if the model has been saved. Since we are going to go through every possible action we are going to make a lot of undo.''' 

====== Accept a difference ======

First accept the modification we have just created. To do so:
* Select the difference you want to accept.
** One click on the difference will select it in the structure merge viewer (top viewer). Double click on it to open the content merge viewer related to this difference.
* Click on the accept icon [[Image:../images/accept_change.gif]].
Your editor should look like this:

[[Image:../images/EMF_Compare_Tuto_New_Book_Difference_Accepted.png]]

A new overlay icon has appeared on the difference. It means that the difference has been merged. You can also notice in the content viewer of the current model version that the book is no more framed. This also means that the difference has been merged.

====== Reject a difference ======

Let's try to reject the difference:
* Undo the previous action using keyboard shortcut (Ctrl+z) or File menu (Edit > Undo).
* Click on the reject icon [[Image:../images/reject_change.gif]].
Your editor should look like this:

[[Image:../images/EMF_Compare_Tuto_New_Book_Difference_Rejected.png]]

The "x" overlay on the difference icon means that it has been rejected. In the content viewer of the current model version the book has disappeared. Indeed, since the modification has been rejected the previous version of this object is used.

===== Set the name of the book =====

We are now going to set the name of the book we have just created. This will change the value of the attribute "Title" to "Prelude to Foundation".
* Close the compare editor (without saving).
* Open the model editor.
* Set the name of the book to "Prelude to Foundation".
** Select the book.
** Display the Properties view: Contextual menu > Show property view.
** Fill the title field.
* Save.

[[Image:../images/EMF_Compare_Tuto_Setting_Book_Name.png]]

Now let's compare it with previous version (see previous chapter for explanation [[#Compare with previous version]]).

[[Image:../images/EMF_Compare_Tuto_Book_Name_Comparison.png]]

On the difference you see the overlay indicating that this difference is a change. This difference is a set on the feature "Title". If you look on the content viewer of the current version, you will see the new value of the feature whereas in the previous version nothing is displayed.

If you accept the difference you will notice the same effect than in the previous chapter (see [[#Accept a difference]]).

[[Image:../images/EMF_Compare_Tuto_Book_Name_Accepted.png]]

If you reject the difference the name of the book will be unset since it has not been set in the previous version (see [[#Reject a difference | Reject a difference]]).

[[Image:../images/EMF_Compare_Tuto_Book_Name_Rejected.png]]

===== Change the category of the book =====

We are going to define that this book is a Science Fiction book. This will change the value of the "Category" feature of the book from its default value "Mystery" to "ScienceFiction".

* Close the compare editor (without saving).
* Open the model editor.
* Change the category of the book to ScienceFiction:
** Select the book.
** Open the property view.
** Change the value of the "Category" feature.
* Save.

[[Image:../images/EMF_Compare_Tuto_Setting_Book_Category.png]]

Now let's compare it with its previous version (see previous chapter for explanation [[#Compare with previous version | Compare with previous version]]).

[[Image:../images/EMF_Compare_Tuto_Book_Category_Comparison.png]]

On the content viewer of the current version you see the new value of the feature "Category" whereas in the previous version the default value is displayed.

Accept the difference and you obviously see (see [[#Accept a difference | Accept the difference]]):

[[Image:../images/EMF_Compare_Tuto_Book_Category_Accepted.png]]

Reject the difference to set the "Category" feature to it's default value (see [[#Reject a difference]]).

[[Image:../images/EMF_Compare_Tuto_Book_Category_Rejected.png]]

===== Fill the library with employees =====

To fill your library we are going to add some employees.
* Close the compare editor (without saving).
* Open the model editor.
* Create an employee name Chief.
* Create an employee name Master.
* Create an employee name Employee.
* Save.

[[Image:../images/EMF_Compare_Tuto_Fill_Employees.png]]

For this step we are not going to compare with the previous version of the model. EXTLibrary stores persons in feature maps. For the moment feature maps are not correctly handled by EMF Compare. Features map comparison will be integrated for the next Eclipse release (Mars in 2015).

===== Set a manager =====

Let's set the manager of "Employee" to "Chief". This will set the reference "Manager" of "Employee" to "Chief".
* Select the employee "Employee".
* Open the Properties view.
* Make the "Manager" feature point to "Chief".
* Save.

[[Image:../images/EMF_Compare_Tuto_Set_Manager_Chief.png]]

Now let's compare it with its previous version (see previous chapter for explanation [[#Compare with previous version | Compare with previous version]]).

[[Image:../images/EMF_Compare_Tuto_Set_Manager_Chief_Comparison.png]]

You can notice the change in the content viewer. However it is slightly  different from the previous comparison. In the content viewer, you now have a new top image.

[[Image:../images/EMF_Compare_Tuto_Top_Image_Reference.png]]

It means that the current difference is a non containment reference. If you look back to [[#Compare with previous version]] the content viewer is not the same since the feature involved was a containment reference.

Accept this difference and you will see the same type of result than [[#Accept_a_difference | Accept a difference]].

[[Image:../images/EMF_Compare_Tuto_Set_Manager_Chief_Accepted.png]]

Reject this difference and you will see the same type of result than [[#Reject_a_difference | Reject a difference]].

[[Image:../images/EMF_Compare_Tuto_Set_Manager_Chief_Rejected.png]]

===== Change of manager =====

Let's say "Employee" has a new job and so he has a new manager. We have to change the feature "Manager" from "Chief" to "Master".
* Close EMF Compare editor (without saving).
* Open the model editor.
* Select "Employee".
* Set the feature "Manager" to "Master".
* Save.
* Compare with previous.

[[Image:../images/EMF_Compare_Tuto_Change_Manager_Master_Comparison.png]]

Accept the change to mark the difference as merged. Reject it to reset the manager of "Employee" to "Chief".

[[Image:../images/EMF_Compare_Tuto_Change_Manager_Master_Reject.png]]

===== No more manager =====

Let's say that "Employee" has reached the top of the command chain. That is to say he has no more manager.
* Close EMF Compare editor (without saving).
* Open the model editor.
* Select "Employee".
* Unset the feature "Manager" of "Employee".
** Open Properties view.
** Select "Manager" field.
** Use the "Restore Default Value" button in the toolbar.
[[Image:../images/EMF_Compare_Tuto_Unset_Employee_Manager.png]]
* Save.
* Compare with previous.
[[Image:../images/EMF_Compare_Tuto_Unset_Employee_Manager_Comparison.png]]

The difference is the opposite of [[#Set_a_manager | set a manager]].
* Accept the difference to get:
[[Image:../images/EMF_Compare_Tuto_Unset_Employee_Manager_Comparison_Accepted.png]]

* Reject the difference to get:
[[Image:../images/EMF_Compare_Tuto_Unset_Employee_Manager_Comparison_Rejected.png]]

===== Add borrowers =====

Let's open the gates of your library to the public. We are going to add borrowers to this library.
 
* Close EMF Compare Editor (without saving).
* Open the model editor.
* Add a new borrower named Will Graham.
[[Image:../images/EMF_Compare_Tuto_Fill_Borrowers.png]]

For the same reason explained in [[#Fill_the_library_with_employees | Fill the library with employees]] we are not going to compare the model this time.

===== Borrowing a book =====

We are going to use your newly created borrower by making him borrow "Prelude to foundation".
* Open the model editor.
* Select "Borrower Graham".
* Add "Prelude to foundation" to the feature "Borrowed" of "Will Graham".
* Save.
[[Image:../images/EMF_Compare_Tuto_Graham_Borrows_Book_Setting.png]]
* Compare with previous.
[[Image:../images/EMF_Compare_Tuto_Graham_Borrows_Book_Comparison.png]]

In this comparison you can notice two differences: [[Image:../images/EMF_Compare_Tuto_Graham_Borrows_Book_Comparison_Borrowers_Diff.png]] and [[Image:../images/EMF_Compare_Tuto_Graham_Borrows_Book_Comparison_Borrowed_Diff.png]]. EMF Compare displays two differences whereas you have only made one modification in your model. The explanation is within the structure of the EXTlibrary metamodel. If you look on the feature "borrowed" in extlibrary.ecore you will see that the EOpposite field is set to "borrowers : Borrower".

[[Image:../images/EMF_Compare_Tuto_Graham_Borrows_Book_Comparison_EOpposite.png]]

This means that each time you add/remove a book to a borrower EMF will automatically add/remove the borrower to the "borrower" features of the book (and the other way around). Modifying one feature will modify the other. It explains why EMF Compare see two differences. 

Now you may wonder what happens when you accept one of the difference? EMF Compare give you a hint on this matter. First notice the consequences preview button [[Image:../images/EMF_Compare_Tuto_Consequences_Preview_Button.png]]. It can either have its icon set to [[Image:../images/accept.gif]] for "Accept preview mode" or [[Image:../images/reject.gif]] for "Reject preview mode". 

When the "Accept preview mode" is activated ([[Image:../images/accept.gif]]), EMF Compare will help you to understand the consequences of accepting the current selected difference. Let's try it.
* Activate the "accept preview mode" ([[Image:../images/accept.gif]]).
* Select "Borrower Graham  <nowiki>[borrowers add]</nowiki>" difference.
[[Image:../images/EMF_Compare_Tuto_Graham_Borrows_Book_Comparison.png]]

Notice that "Book Prelude to Foundation <nowiki>[borrower add]</nowiki>" difference is highlighted in green. This means that accepting the current difference will automatically accept this difference too. Those two differences are linked by an "Equivalence" element meaning that merging one is equivalent to merge the other. You can reproduce the same behavior by selecting the difference "Book Prelude to Foundation <nowiki>[borrower add]</nowiki>" instead of "Borrower Graham  <nowiki>[borrowers add]</nowiki>".

* Accept the difference and check out the result.

[[Image:../images/EMF_Compare_Tuto_Graham_Borrows_Book_Comparison_Accepted.png]]

Both differences have been accepted. 
Now let's try to reject the difference. 
* Undo the previous merge (Ctrl+z).
* Switch to the reject preview mode([[Image:../images/reject.gif]]).
[[Image:../images/EMF_Compare_Tuto_Switch_Reject_Preview_Mode.png]]
* Select one difference.
** Notice that the other difference is also highlighted in green. Since the two differences are "equivalent" both preview mode show the same consequences. You will see later in another use case that each preview mode can show different consequences.
* Reject the difference.
[[Image:../images/EMF_Compare_Tuto_Graham_Borrows_Book_Comparison_Rejected.png]]

Both differences have been rejected.

===== Create a new library branch =====

Now that's your library is growing, let's create a new branch in your library. This new library will be affiliated to the main entity but will have an independent live. 
* Close EMF Compare Editor (without saving).
* Open the model editor.
* Create a new library under your main library.
* Create a new book in this new element called "1984".
* Save.
[[Image:../images/EMF_Compare_Tuto_New_Library_Setting.png]]
* Compare with previous.
[[Image:../images/EMF_Compare_Tuto_New_Library_Comparison.png]]

EMF Compare displays only one difference whereas you have made two modifications. You have created one sub library and one book. There must be a connection between those two differences... Indeed without the library it's impossible to create the book "1984" since it is included in the new library. That's why by default EMF Compare does not display the two differences.
* Accept the difference.
[[Image:../images/EMF_Compare_Tuto_New_Library_Comparison_Accepted.png]]

EMF Compare has accepted both differences. It has created the new library and the new book. On the contrary if you reject the difference.
* Reject the difference
[[Image:../images/EMF_Compare_Tuto_New_Library_Comparison_Rejected.png]]

EMF Compare rejects both differences.

In some use cases it can be useful to display both differences. For example if we would like to accept the creation of the library but reject the creation of the book. To do so, you have to use the filter button ( see [[./../user/user-guide.html#Filtering_Differences | Filtering Differences]] for further information).
* Undo the previous action (Ctrl+z).
* Deactivate "Cascading difference" filter.
[[Image:../images/EMF_Compare_Tuto_New_Library_Comparison_Cascading_Filter.png]]
* Click on "No". It tells EMF Compare not to remember your choice for subsequent comparisons.

[[Image:../images/EMF_Compare_Tuto_New_Library_Comparison_Cascading_Filter_Popup.png]]

Once the filter has been deactivated you will see both differences. Now you can merge separately each difference.

* Activate "Accept preview mode" ([[Image:../images/accept.gif]]).
* Select the book difference "Book 1984 <nowiki>[stock add]</nowiki>".

[[Image:../images/EMF_Compare_Tuto_New_Library_Comparison_Cascading_Filter2.png]]

Notice that the library difference is highlighted. Indeed, merging the book difference will necessarily merge the library difference. 

* Switch to "Reject preview mode" ([[Image:../images/reject.gif]]).

[[Image:../images/EMF_Compare_Tuto_New_Library_Comparison_Cascading_Filter3.png]]

In this mode the other difference is not highlighted. Indeed, you can reject the creation of the book without rejecting the creation of the library. In the same way, selecting the library difference while "Reject preview mode" is activated will highlight the book difference. If the library does not exist then the book can not exist.
* Activate "Reject preview mode" ([[Image:../images/reject.gif]]).
* Select the library difference.

[[Image:../images/EMF_Compare_Tuto_New_Library_Comparison_Cascading_Filter_Reject_Mode.png]]

===== Move a book =====

In order to fill the new library we are going to give it one book from the main library. 
* Close EMF Compare editor (without saving).
* Open the model editor.
* Move "Prelude to Foundation" to the new branch library (using drag and drop).
* Save.
[[Image:../images/EMF_Compare_Tuto_New_Library_Move_Setting.png]]
* Compare with previous.
[[Image:../images/EMF_Compare_Tuto_New_Library_Move_Comparison.png]]

With this example we have introduced a new type of change: "moving an element". That is to say the element existed in the previous version but was located in a different place. In the content viewer you can see the location of this element in the current and previous versions of your model.

* Accept the change to mark the difference as merged.

[[Image:../images/EMF_Compare_Tuto_New_Library_Move_Accepted.png]]

* Reject the difference to move back the element to its original location.

[[Image:../images/EMF_Compare_Tuto_New_Library_Move_Rejected.png]]

===== Remove a book =====

After an accident the book "1984" has to be removed from the shelves.
* Close EMF Compare editor (without saving).
* Open the model editor.
* Delete the book "1984".
* Save.

[[Image:../images/EMF_Compare_Tuto_Remove_Book_Setting.png]]

* Compare with previous.

[[Image:../images/EMF_Compare_Tuto_Remove_Book_Comparison.png]]

This kind of change is the opposite of an addition. 
Accept the change to mark the difference as merged.

[[Image:../images/EMF_Compare_Tuto_Remove_Book_Accepted.png]]

Reject it to add the book back into the library.

[[Image:../images/EMF_Compare_Tuto_Remove_Book_Rejected.png]]

==== Compare with repository (3-way) ====

===== Set up =====

In this part of the tutorial we are going to continue building our model. The only difference is that we are going create different scenarios for each new modification. To do this we need a tool called Git. It is a free and open source distributed version control system. In Eclipse world we are going to talk about [[http://www.eclipse.org/jgit/ |JGit]] and [[http://www.eclipse.org/egit/ |EGit]]. JGit is a java implementation of Git. EGit is the integration of JGit in Eclipse. 

====== Create a Git repository ======

First of all we need a Git repository. You can either use a clone of an existing Git repository or create your own local Git repository. We have chosen the second solution for this tutorial.
* Open the "Git Repositories" view (if not already open): Window > "Show view" > "Other...".
** Select "Git Repositories".
**: [[Image:../images/EMF_Compare_Tutorial_Git_Repo_View.png]]
* Then click on the new repository button [[Image:../images/EMF_Compare_Tuto_Create_Git_Repo_Button.png]].
* Set the location of your new repository and give it a name.
*: [[Image:../images/EMF_Compare_Tuto_Create_Git_Repo_Wizard.png]]
* Click on finish.
*: [[Image:../images/EMF_Compare_Tuto_Repository_View.png]]

====== Share your model ======

Now that your repository is ready. Let's put your model in it.
* Select the project holding your model.
* Open the contextual menu: Team > "Share project...".
*: [[Image:../images/EMF_Compare_Tuto_Share_Project.png]]
* Select "Git" and click next.
*: [[Image:../images/EMF_Compare_Tuto_Share_Project_Wizard.png]]
* Choose the repository you have just created and click on finish.
*: [[Image:../images/EMF_Compare_Tuto_Share_Project_Wizard2.png]]

====== Commit your changes ======

Your project has just been moved into the repository. However your work has not been committed yet. Committing a model is like taking a snapshot of it and save it for later (see [[http://wiki.eclipse.org/EGit/User_Guide#Committing_Changes | Commiting Changes]] for further information). To do so:

* Select the project holding your model.
* Open the contextual menu: Team > "Commit...".
* Enter a message for this commit describing what has been done. In this example we wrote "First commit."
* Select the files you want to commit. In our example select all files.
*: [[Image:../images/EMF_Compare_Tuto_First_Commit.png]]
* Click on commit button.

Your project has just been committed into your repository. 
Let's have a look at your repository and its history.
* Select your repository in the "Git Repositories view".
* Open the the "History view":
** Open the history view: Window > "Show view" > "Other...".
** Select "History".
**: [[Image:../images/EMF_Compare_Tuto_History_View.png]]

It should look like this.
[[Image:../images/EMF_Compare_Repository_State1.png]]

Expand your repository tree in the "Git repository" view. In it you can see a folder named "Local". This folder contains all the branches of you Git repository. You can picture yourself that each branch is a scenario of your model. You can notice that your repository has already a "master" branch. This is your main scenario. 

On the history view you will be displayed the graph of all your commit. Currently the only entry available is the first commit you have made earlier. To better understand the changes that we are going to make in the repository, We advice you to click on "Synchronize" button ([[Image:../images/EMF_Compare_Tuto_Sync_Button.png]]) and on "Show all branches" button ([[Image:../images/EMF_Compare_Tuto_Show_All_Branches_Button.png]]). This will give you a global point of your repository.

===== Create Scenario 1 =====

Let's create our first scenario. To do so:
* Select the branch that will be used as start point your new branch. In this case, master.
* Open the contextual menu: "Create new branch...".
[[Image:../images/EMF_Compare_Tuto_Create_New_Branch.png]]
* Set its name to "Scenario1". The button "Checkout new branch" must be checked.
[[Image:../images/EMF_Compare_Tuto_Create_New_Branch_Wizard.png]]
* Click on finish.

You have just created a new scenario that will use the last commit from master branch as starting point.

====== Change the number of page ======

You have now two branches in your repository. Let's modify our model to write our first scenario.
* Open the model editor.
* Select the book "Prelude to Foundation".
* Open the "Properties" view.
* Change the value of the field "Pages" to 374.
* Save.
[[Image:../images/EMF_Compare_Tuto_Scenario1_Setting.png]]
* Compare this model with the last commit in your repository:
** Select your model file.
** Open the contextual menu: "Compare With" > "Head Revision".
[[Image:../images/EMF_Compare_Tuto_Scenario1_Comparison.png]]

This is a comparison between the current version of your model and the snapshot that you have committed earlier. Let's save this version. To do so we are going to commit it. Follow the step described in [[#Commit_your_changes | Commit your changes]].
* Select the project holding your model.
* Open the contextual menu: Team > "Commit...".
[[Image:../images/EMF_Compare_Tuto_Scenario1_Commit.png]]
* Enter the commit message: "Set page number to 374".
[[Image:../images/EMF_Compare_Tuto_Scenario1_Commit_Message.png]]
* Click on commit.

===== Scenario 2: Conflict =====

Let's create a different scenario. Follow the step described in [[#Create_Scenario_1 | Create Scenario 1]] to create a new scenario called "Scenario2" from the master branch.
* Click on the master branch in the "Git Repositories view".
* Open the contextual menu: "Create new Branch...".
* Set the name of the new branch to "Scenario2".
* Click on finish.
[[Image:../images/EMF_Compare_Tuto_Scenario2_Creation.png]]

In this scenario we are going to set the number of pages of "Prelude to Foundation" to 375.
* Open your model editor.
* Set the number of page of "Prelude to Foundation" to 375 (see [[#Change_the_number_of_page | Change the number of page]] for further information)
* Save.
*: [[Image:../images/EMF_Compare_Tuto_Scenario2_Setting.png]]
* Commit your changes (see [[#Commit_your_changes | Commit your changes]] for further information).
* Set the commit message to "Set page number to 375."
* Compare your model with the scenario 1:
** Select the model file.
** Open the contextual menu: "Compare with" > "Commit...". 
**: [[Image:../images/EMF_Compare_Tuto_Scenario2_Compare_With_Commit.png]]
** Select the commit that holds the "Scenario1" tag.
**: [[Image:../images/EMF_Compare_Tuto_Scenario2_Compare_With_Commit2.png]]

You should now have an EMF Compare editor open.

[[Image:../images/EMF_Compare_Tuto_Scenario2_Comparison.png]]

The first thing to understand is that this comparison is a 3-way comparison. This means that EMF Compare has used 3 inputs to compute the differences. The first one (on the bottom left) is the local version of your model (Scenario2). The second one (on the bottom right) is the version of your model from Scenario 1. And the third one is a common ancestor of the two other versions. The history view gives a picture of the situation.
* Have a look on the history view of your repository.

[[Image:../images/EMF_Compare_Tuto_Scenario2_Common_Ancestor.png]]

Both scenario 1 and 2 used the master branch as starting point. This is why it has being used as common ancestor. We will see later on this tutorial how EMF Compare uses this third input. You can display its content in the user interface by clicking on "Show ancestor button" ([[Image:../images/EMF_Compare_Tuto_Show_Ancestor_Button.png]]).

<div id="EMF_Compare_Tuto_Scenario2_Common_Ancestor_Img"></div>
[[Image:../images/EMF_Compare_Tuto_Scenario2_Common_Ancestor2.png | Common Ancestor 2]]

* Let's have a look on the differences.
[[Image:../images/EMF_Compare_Tuto_Scenario2_Conflict_Differences.png]]

You can notice a new type of difference: conflicts. Indeed in scenario 1 we have set number of page to 374 whereas we have set it to 375 in scenario2. EMF Compare is telling us that it can not be both. If you select one of the difference you will see that the other is highlighted in red. This means that if you merge this difference EMF Compare will not be able to merge the other one.

We are now going to see what will be the impact of accepting or rejecting each difference.
* Select the difference named "375 <nowiki>[page changed]</nowiki>".
* Accept the difference.

[[Image:../images/EMF_Compare_Tuto_Scenario2_Accept_375.png]]

In this case EMF Compare has accepted the selected difference and rejected the other since they can not be accepted both. Let's try to reject this difference.
* Undo the previous action (Ctlr+z)
* First switch to "Reject preview mode" ([[Image:../images/reject.gif]]).
[[Image:../images/EMF_Compare_Tuto_Scenario2_Reject_Preview_Mode.png]]
You can notice that there is nothing highlighted in red. It seems that rejecting this difference has no consequence on other differences. Let's find out.
* Reject the difference named "375 <nowiki>[page changed]</nowiki>".
[[Image:../images/EMF_Compare_Tuto_Scenario2_Reject_375.png]]

In this case it has only rejected the current difference. If you look at the value of the attribute you will see that the number of page has been set to 100. This value is the value of the same attribute in the common ancestor model (see [[#EMF_Compare_Tuto_Scenario2_Common_Ancestor_Img | Common ancestor model]]). In 3-way comparison you can either accept the version of an attribute from one of the two input version (Scenario 1 or Scenario 2) or return the version to its common ancestor value (master).

Obviously you can do the same actions on the difference named "374 <nowiki>[page changed]</nowiki>". It will:
* Set the value of the attribute to 374 and reject the other difference if you accept it.
* Set the value of the attribute to 100 if your reject it.

===== Scenario 3: Pseudo conflict =====

In the previous chapter you have seen how EMF Compare handles two conflicting changes between two scenarios. In this chapter we are going to see how it handles two changes that are semantically the same. Let's create the scenario 3.
* Create a new branch named scenario 3 from master (see [[#Create_Scenario_1 | Create Scenario 1]] to see how to create a new scenario).
* Open your model editor.
* Set the number of page of "Prelude to foundation" to 375 (see [[#Scenario_2:_Conflict | Scenario 2]] for further explanation).
* Save.
* Commit your changes (see [[#Commit_your_changes | Commit your changes]]). Set the commit message to "Set page number to 375".
* Compare this version with the scenario 2 :
** Select your model file.
** Open the contextual menu: "Compare with" > "Branch, Tag or Reference...".
**: [[Image:../images/EMF_Compare_Tuto_Scenario3_Compare_With_Branch.png]]
** Select scenario 2.
**: [[Image:../images/EMF_Compare_Tuto_Scenario3_Compare_With_Scenario2.png]]
** Click on Compare.

[[Image:../images/EMF_Compare_Tuto_Scenario3_Comparison.png]]

At first glance it's seems that nothing has been done. This would not really be surprising since the two input models are semantically identical. However you will see that EMF Compare has done some work. To see it:
* Deactivate the "Pseudo Conflict" filter.
* Handle the filter popup. Select "Yes" if you want to deactivate the "Pseudo conflict" filter by default for all subsequent comparisons. Select "No" if you prefer deactivating it only for the current comparison. You can also ask EMF Compare to remember your choice by checking the checkbox in the bottom left corner.
* [[Image:../images/EMF_Compare_Tuto_New_Library_Comparison_Cascading_Filter_Popup.png]]
''' Blocked  by https://bugs.eclipse.org/bugs/show_bug.cgi?id=435051 '''
[[Image:../images/EMF_Compare_Tuto_Scenario3_Pseudo_Conflict_Filter.png]]

EMF Compare has detected two differences. The first difference has been detected between the common ancestor and the scenario 2. The second has been detected between the common ancestor and the scenario 3. However EMF Compare was clever enough to consider that those two differences were the same. 

 
'' TODO Create a new scenario - Scenario 4 and 5 Advanced conflict (Compare with another branch + Advanced conflict)''
===== Scenario 4 and 5: Advanced conflict =====

Now that you have understood how conflicts works we are going to create a more complex conflict. Let's create a conflict between a book that we are going to delete in a scenario (Scenario4) and the same book that we are going to borrow in another scenario (Scenario 5). 
* Create a new scenario named "Scenario4" from master (see [[#Create_Scenario_1 | Create Scenario 1]] to see how to create a new scenario).
* Delete the book "Prelude to foundation".
* Save.
*:[[Image:../images/EMF_Compare_Tuto_Scenario4_Setting.png]]
* Commit with the message "Deletion of prelude to foundation" (see [[#Commit_your_changes | Commit your changes]]).
*: [[Image:../images/EMF_Compare_Tuto_Scenario4_Commit.png]]
* Create a new scenario "Scenario5" from master (see [[#Create_Scenario_1 | Create Scenario 1]] to see how to create a new scenario).
*: [[Image:../images/EMF_Compare_Tuto_Scenario5_Branches.png]]
At this stage of the tutorial your Git repository should look like this.
* Make "Will Graham" borrows "Prelude to foundation".
* Save.
*: [[Image:../images/EMF_Compare_Tuto_Scenario5_Setting.png]]
* Commit with the message "Will Graham borrows a book" (see [[#Commit_your_changes | Commit your changes]]).
* Compare scenario 5 with scenario 4 (see [[#Scenario_3:_Pseudo_conflict | Compare with branch]] for further information).
*: [[Image:../images/EMF_Compare_Tuto_Scenario5_Comparison.png]]

If you select each differences you will see that:
* "Book Prelude to foundation<nowiki>[stock delete]</nowiki>" can not be merged with the two other differences.
*: [[Image:../images/EMF_Compare_Tuto_Scenario5_Diff_Dependencies.png]]
** Accept the difference to get:
**: [[Image:../images/EMF_Compare_Tuto_Scenario5_Deletion_Accepted.png]]
** Reject the difference to get:
**: [[Image:../images/EMF_Compare_Tuto_Scenario5_Deletion_Rejected.png]]
**: Rejecting it does not automatically accept the other differences. Indeed you can prevent the deletion of the book but still want to choose to accept or reject the other difference.
* "Borrower Graham<nowiki>[borrowers add]</nowiki>" and "Book Prelude to foundation<nowiki>[borrowed add]</nowiki>" are equivalent and they can not be merged with the third difference.
*: [[Image:../images/EMF_Compare_Tuto_Scenario5_Diff_Dependencies2.png]]
** Accept one of the of them to get:
**: [[Image:../images/EMF_Compare_Tuto_Scenario5_Set_Ref_Accepted.png]]
** Reject one of the them to get:
**: [[Image:../images/EMF_Compare_Tuto_Scenario5_Set_Ref_Rejected.png]]
**: The same conclusion goes here. You can reject the setting of the reference and still want to choose what to do with the "delete" difference.

===== Fragment your model =====

Let's say that you want to delegate the work on the sub library to one of your colleague. To do so you want to give him a file with in it the sub library and only this. Let's extract our new branch library into a new file. In this part of the tutorial we are going to discuss the fragmentation of a model (also called control). The following steps will show you how EMF Compare reacts with model split among several files. 

* Create scenario 6 from master (see [[#Create_Scenario_1 | Create Scenario 1]] to see how to create a new scenario).
* Open the model editor.
* Control the branch library:
** Select the sub library.
** Open the contextual menu: "Control...".
**: [[Image:../images/EMF_Compare_Tuto_Control_Library.png]]
** Set the path of the new target file (Use "Browse Workspace..." button for convenience).
**: [[Image:../images/EMF_Compare_Tuto_Control_Library_Set_URI.png]]
* Save (A new file appears in your project).
* Close the model editor.
* Open the model editor (it needs to be reloaded to see the control decorator).
[[Image:../images/EMF_Compare_Tuto_Controled_Model.png]]
In your new model you can see that two resources have been loaded (NewLibraryFile.extlibrary and TutorialModel.extlibrary). You can also notice a new overlay icon on the sub library. This means this element is stored in another file (resource).
* Compare with HEAD (see [[#Change_the_number_of_page | Compare with HEAD]]).
Eclipse asks you to switch to the "Team Synchronize" perspective, accept.


'''Blocked https://bugs.eclipse.org/bugs/show_bug.cgi?id=435081'''

''TODO when included in repository - Rebase two branch - Rebase your work on the work of your colleague''
''TODO when included in repository - Merge two branch - Merge the work with your colleague''