Table Of Contents

Before you Start

Installation and Configuration

Installation

Repository Integration

Integrating with ClearCase Explorer

Integrating with TortoiseSVN

Integrating with another Repository Client

Configuring MATLAB/Simulink Installations

Changing Window Positions

Starting SimMerge

3-way Merge vs 2-way Merge

Using SimMerge

Toolbar Buttons

Info Panel

Merge Actions

Conflicts and Dependencies

Undoing merge actions (lab feature)

Stateflow Support

Legal Notice

SimMerge's merge is the easiest and most reliable way to integrate changes from different team members into a single Simulink model. It provides three modes of operation, 3-way merge, 2-way merge and comparison mode. It comes in two versions, LT and Pro. The only differerence between them is that the former lacks the 3-way merge feature. We highly encourage you watch the flash demo.

After that you can use this manual as a quick reference while using SimMerge. Its small width makes it fit perfectly next to SimMerge on your monitor.

Requesting Support from EnSoft

If you have any questions you can send an e-mail to support@ensoftcorp.com. If you have a general question about SimMerge please include it in the body of your email.

If you experience an error while running SimMerge please include your SimMerge log.
You can open the log by selecting:
Start ▷All Programs ▷EnSoft ▷SimMerge ▷SimMerge Log

Save it to a location of your choice and attach it to your email.

Terminology

Throughout this manual and the SimMerge user interface the following terms for models are used:
Target Model: The model where changes will be merged into. This is the model you modified.
Contributor Model: The model from which you are pulling changes. This is the model stored in the repository.
Base Model: The most recent common ancestor to the target and contributor models.
Lab feature: these are features that are in an experimental phase. That means they may not work as expected and/or there could be some limitations in their usage. They could also be modified or removed in a future release.

---

Installation

Run the SimMerge installer from the e-mail you received from EnSoft, or your SimMerge Installation CD, and follow the onscreen instructions.

The first time you run SimMerge you will be asked to enter your license key or license server information.

Repository Integration

SimMerge works best when integrated into your repository client. The sections below include instructions for integrating SimMerge with ClearCase Explorer and other repository clients. Note that only SimMerge Pro can be integrated with a repository for merge purposes since it provides the 3-way merge feature.

Integrating with ClearCase Explorer

Run ▷Start ▷All Programs ▷EnSoft ▷SimMerge ▷ClearCase Integration Tool.

Then follow the instructions below.

• 1 Select the directory Clearcase is installed in.
• 2 Select the directory SimMerge is installed in.
• 3 Click on the Install or Update button.
• 4 Select the VOB Configuration tab.
• 5 Select the VOB(s) containing MDL files.
  Multiple VOBs can be selected by holding the CTRL key while clicking each VOB following the first.
• 6 Click on the Install/Update on Selected button.

Integrating with TortoiseSVN

Merge Tool Setup

• 1 Open the TortoiseSVN Settings dialog: ▷TortoiseSVN ▷Settings
  (in the Explorer right-click context menu.)
• 2 Select the ▷External Programs ▷Merge Tool page.
• 3 Click the Advanced button to open theAdvanced merge settings dialog.
• 4 Click Add... to add a new extension-specific merge tool.
• 5 In the dialog that opens, use ".mdl" for the extension, and the following for the external command:
  "C:\Program Files\EnSoft\SimMerge\simmerge.exe" %base %mine %theirs %merged
• 6 Click OK for each open dialog to save settings.

Merging model files using TortoiseSVN

TortoiseSVN only uses external merge tools to resolve conflicts it cannot handle on its own. This means that SimMerge will not always be invoked when merging model files.

If a file is changed in a branch, but left unchanged in the main branch, then merged to the main branch, TortoiseSVN will perform a simple file copy, rather than invoke SimMerge to perform the merge.

TortoiseSVN will not immediately invoke SimMerge when it is unable to perform a simple merge. Instead, it will mark the file as being "in conflict". SimMerge can then be invoked by right-clicking the file and selecting "Edit conflicts" from the context menu.

Here is an example of the steps taken in a typical merge of a branch with conflicting model files using TortoiseSVN:

• 1 Begin merging by selecting Merge... from the right-click context menu
• 2 After selecting the merge type and revisions using the wizard, press the Merge button from within the wizard to begin the merge process.
• 3 TortoiseSVN will notify the user that some changes are in conflict and cannot be automatically resolved. At this point, the user should select Resolve All Later.
• 4 Inside the repository, the conflicting files will be marked with a yellow triangle. SimMerge can resolve conflicts by right-clicking a conflicting file and selecting Edit Conflicts from the context menu.
• 5 After the conflict is resolved, and SimMerge is closed, right-click the file and select Resolved... from the context menu.
• 6 Once all files are resolved, the merged changes can be committed to the repository, and the merge is complete.

Diff Tool Setup

Both versions of SimMerge (LT and Pro) can be setup as a diff tool by following the instructions under the "Merge Tool Setup" heading, with the following modifications:

• 1 Open the TortoiseSVN Settings dialog: TortoiseSVN ▷Settings
  (in the Explorer right-click context menu).
• 2 Select the External Programs ▷Diff Viewer page.
• 3 Click the Advanced button to open the Advanced merge settings dialog.
• 4 Click Add... to add a new extension-specific merge tool.
• 5 In the dialog that opens, use ".mdl" for the extension, and the following for the external command:
  "C:\Program Files\EnSoft\SimMerge\simmerge.exe" %base %mine %base
• 6 Click OK for each open dialog to save settings.

There are many ways that TortoiseSVN will invoke SimMerge as an external diff viewer, such as when comparing a file with the previous version. To do this, right-click a model file with at least two revisions stored in the current branch, and select "Diff with previous version" from the context menu.

Integrating with another Repository Client

Most repository clients allow you to specify an external tool to merge specific file types. For instructions, please consult your repository client's documentation.

For most clients you will be asked to enter a command to execute. To use SimMerge as your external tool, use this command:
"C:\Program Files\EnSoft\SimMerge\SimMerge.exe"
baseMDL targetMDL contribMDL [outputMDL]
(please use the path to your specific SimMerge installation)

Replace baseMDL, targetMDL, and contribMDL with the appropriate syntax for your client. Some repository clients require a separate output file; to do this add a fourth parameter to specify the output file.

If your repository client adds an invalid character to the model name that would prevent Simulink from opening it, SimMerge will automatically remove it.

If your repository client does not allow you to specify a merge tool for .mdl files and another merge tool for text files, you can use mergetool.bat included in:
C:\Program Files\EnSoft\SimMerge\utils
(or wherever SimMerge is installed).

To use mergetool.bat, modify the section titled "HANDLE NON-MDL FILES" to call your text merge tool, then configure your repository client to call mergetool.bat. mergetool.bat will call SimMerge for mdl files and your text merge tool for all other files.

Configuring MATLAB/Simulink Installations

The first time SimMerge runs it will automatically detect MATLAB/Simulink installations on your computer. You can rerun the auto-detection process, or add and remove installations manually, through the preferences:
▷File ▷Preferences.

Changing Window Positions

SimMerge will make optimal use of your display by organizing SimMerge and Simulink windows. You can change the default positions in the preferences:
▷File ▷Preferences.

---

If you have configured SimMerge to run from a repository client then you can skip this section and go to the next section titled "Using SimMerge".

If you start SimMerge directly instead of through a repository client a screen will appear prompting you to enter the files you wish to compare or merge.

1. Select a Mode

3-way Merge:This is the easiest and most reliable way to merge models. You will need to provide SimMerge with 3 models (more information about 3-way merge vs 2- way merge below).

2-way Merge:You should only use this mode when you do not have the three models necessary for a 3-way merge.

Comparison: When you simply want to compare two models without merging changes. This mode disables the merge buttons in SimMerge so you cannot accidentally modify your models.

2. Select Models to Merge

Depending on the mode you choose there are up to three different models that SimMerge will use:

Target Model:The model where changes will be merged into. This is the model you modified.

Contributor Model:The model from which you are pulling changes. This is the model stored in the repository.

Base Model:The most recent common ancestor to the target and contributor models.

3. Begin Merge or Comparison

After choosing a mode and specifying your models click on Start.

3-way Merge vs 2-way Merge

A 3-way merge is more reliable than a 2-way merge because it tells the user how models were changed, not just how they differ.

Original Model
A
B

For example, suppose the model above was modified by two users resulting in the two models below.

Model 1	Model 2
A	A
B
	C
D

⇐Same

⇐Different

⇐Different

⇐Different

A 2-way merge of the models can just tell whenever two elements are same or different. Without examining the original there is no way of knowing if D was added to Model 1 or if D was deleted from Model 2. SimMerge's 2-way merge approach always assumes the change occurred in the contributor model. Therefore, in the above example it will report D as deleted. It is the user responsability to decide whether D should be deleted or kept in the merged model. Note that in all 2-way merge tools the resulting merged model will be determined by user decisions during the merging process.

In contrast a 3-way merge will examine the original model along with the two models to be merged to tell us how the models were changed.

Model 1	Model 2
A	A
B
	C
D

⇐Same

⇐Deleted

⇐Added

⇐Added

With this information it is straightforward to produce the merged model below.

Merged Model
A
C
D

---

SimMerge shows your model on the left and the model in the repository the right. The changes made to both models are also indicated. You can double click any element in the model and SimMerge will show it in a Simulink window.

You can merge a difference by clicking one of the merge action buttons between the models—it's that simple!

If you want to merge something manually you can edit your model in its Simulink window and then click the synchronize button in SimMerge. SimMerge will automatically make backup copies of your models when you start merging. By default backup copies are stored in:
"...\My Documents\SimMerge\model-backup" for 7 days.

You can change this in the preferences:
File ▷Preferences.

Info Panel

The Info Panel gives a plain language description of the currently selected element. It's very handy if you are new to SimMerge.

Merge Actions

Merge actions are indicated by a colored arrow in between the two model trees.

When an element has been added in the contributor model, you can click on this merge action to add the same block in the target model.

When an element has been deleted from the contributor model, you can click this merge action to delete the same block in the target model.

When an element's attributes have been changed in the contributor model you can click this merge action to copy these attribute changes to the target model.

Conflicts and Dependencies

If the same element was changed in both the target and contributor this is called a conflict. It means that if the change in the contributor is applied it may overwrite some of your changes in the target model. Note that a change in both, target and contributor, can only be determined when the base model is available. Therefore, conflicts can only be detected in 3-way merge mode.

Some changes depend on other changes. For example, in order to add a signal the blocks it connects must be present. SimMerge knows about dependencies and will automatically apply dependent changes when a merge action is executed.

If a change depends on a conflicting change, it's merge action is shown in orange. Clicking it will apply all dependent merge actions; this may overwrite some of your changes in the target model.

If a change depends on a merge action that cannot be executed it will be blocked. You can attempt to apply this change by modifying the model manually. When you are done click the synchronize button.

You can view dependent merge actions by using the Dependencies tab. The dependencies are organized in a tree, where the children have to be executed before the parents.

Important: After editing the model directly in Simulink you need to let SimMerge know that some changes have occurred. You can do this by clicking the synchronize button.

---

Lab feature.

SimMerge allows undoing/redoing merge actions for Simulink elements. There are some limitations and guidelines to follow for a proper use of this lab feature. For instance, undoing merge actions for Stateflow elements is not supported yet. In order for the undo feature to work properly these are the situations that should be avoided:

• 1 Closing MATLAB: manually closing the MATLAB session SimMerge is connected to could cause loss of undo data. As a consequence, future undo operations could fail. Thus, if the MATLAB session is closed, it's recommended to click the synchronize button and then continue with the merge process.
• 2 Closing target model without saving: if the model has unsaved changes and it is closed without saving, then future undo operations could fail. Thus, if the target model has to be closed without saving, it's recommended to click the synchronize button right after closing it.
• 3 Changing target model: changes manually done in the target model could interfere with undo operations. Thus, you should synchronize after modifying the model.

Note that even if an undo operation fails due to some of the above or other situation, SimMerge still allows you to go to the next undo operation.

Important: note that the undo/redo history is cleared when synchronization is done.

---

SimMerge also supports the merging of Stateflow elements. Since the position of Stateflow elements can have an effect on behavior, extra care must be taken when merging Stateflow. You can use merge actions just as with Simulink, and then adjust positions if necessary.

---

Legal Notice