Comparing and Merging Model Files

The Storyboard Designer model file is a single model file. Conflicting changes to this model file can be visually inspected and merged from within Designer using the model comparison tools.

To compare two Designer files within the same project or file system workspace. Select both of the model files (e.g., file1.gde and file2.gde) in the Navigator view. Right click and select Compare With > Each Other from the menu.

To compare a Designer file that is in under revision control to a previous version, right-click on the file and select the menu entry Compare With. Different version control systems provide different specific terms, but . In the sub-menu you can select Latest from Repository or Revision if you want to compare with a specific version.

In either case, local comparisons or comparisons with versions from a revision control system, the comparison will open an editor that will highlight the differences in the model elements in the two files and allow each of the changes to be viewed in context and merged or discarded as may be required by the final design.

Triggering a comparison provides a hierarchical breakdown of the models' objects, with two sides representing the two files. Any differences between the two models will be highlighted in yellow. The two types of differences are property changes and additions/deletions.

Property changes show the value on both sides of the viewer. Changes are marked by a delta icon between the two tables in the two reference comparison or an arrow representing the direction of the change when three reference points are available. The three reference point comparison is usually only available when a source control system is available to provide the revision history.

For additions/deletions, the side representing the file that has the object will show it, and the other side will show empty space. Additions and deletions are marked by a + or - icon, and an arrow representing the direction of the change when three reference points are available.

In addition to changes, the comparator will also show any unchanged objects/properties, for reference and context. They are displayed in gray text, with no background color. In a three way comparison with an ancestor, it is possible that a conflicting change exists, where both sides have modified the same object/property from the original ancestor. These will be highlighted in red.

The toolbar contains actions and options to merge changes and switch the view. From left to right, here is a description of each one:

After making changes, saving the comparator tab will appropriately save the changes to the model file(s). Exiting the comparator without saving will revert any applied changes. The global undo/redo functions are also available to revert and re-apply changes.

If you are working from a command line environment, or integrating Storyboard project merging into a continuous integration environment where file merges must happen automatically with a binary pass (merge successful) or fail (merge conflict), then Storyboard provides a command line merge tool for you to use: ${SB_DESIGNER_EXT} -nosplash -application com.crank.gdt.merge.gdemerge ${ancestor} ${current} ${other} Here the ${SB_DESIGNER_EXT} represents the path to your Storyboard Designer executable and will vary based on your operating system and installation path. For a standard windows distribution you would find the Storyboard Designer binary in C:\Program Files\Crank Software\Storyboard_Designer\Storyboard.exe while on a MacOS system is may be /Applications/Crank_Software/Storyboard_Designer/

The values of ${ancestor} ${current} ${other} are the full paths to the files being compared and are designed to align with external source management tools such as subversion (svn) and git. The merged content will be stored into the ${current} file by default but can be redirected by specifying -output=newfilename. As an example of how to use this merge command with a command line git client, put the following in your .gitconfig file: [mergetool "mergegde"] cmd = \"C:\\Program Files\\Storyboard_Designer\\Storyboard.exe\" -nosplash -application com.crank.gdt.merge.gdemerge -quiet=1 $BASE $LOCAL $REMOTE trustExitCode = false Assuming that the mergegde is specified as the merge tool for all *.gde files then this will invoke the Storyboard specific merge for model files.

In addition to the merge tool built into Designer, there is a standalone comparator application that allows for an automated merge as well as a manual merge with a visual diff. The application will first attempt an automatic merge of the provided content. If that fails due to the discovery of a conflict, the visual diff will appear and allow the user to merge manually. The application is packaged in Storyboard alongside Designer, and makes use of the exact same command line options as above along with two new ones. Specifying -headless will suppress the visual diff regardless of the result and just attempt an automatic merge, exiting if a failure occurs. Specifying -manual will skip an automatic merge attempt and jump straight into the visual diff of the files. Similarly, this is what a mergetool entry would look like in .gitconfig: [mergetool "mergegde"] cmd = \"C:\\Program Files\\Storyboard_Comparator\StoryboardComparator.exe" [-quiet] [-headless|manual] [output=/path/to/result.gde] $BASE $LOCAL $REMOTE