Arbed - Comparing Real Studio Projects

1.  Comparing two projects

There are several ways to initiate the comparison of two projects:

1. Drop the two project files onto the Project Comparison field of the Arbed Drop Pad window
2. Compare two separately opened projects or classes (note: You can copy a class in the Real Studio IDE and then paste it into Arbed) by choosing Compare Two Front Projects from the Project menu.
3. Invoke Arbed from the command line. That is useful when using Version Control Software such as SmartGit, SourceTree or Tower.

2.  Comparison window

If you compare two projects, you'll see a window with three segments:

The bottom list shows all differences, separated by their location (method, constant, property, etc.) and their type (declaration, source code, etc.). The upper left and right views show the actual differences of the currently selected item from the lower list.

The bottom list shows, from left to right:

• Location of the difference
• Type (Method, Property, Constant, etc.)
• What differs (left only and right only means that this item exists only on the right or left side)
• The left and right side's values (e.g., note the first line where you can see that the left method's scope is "Protected while the right one's is Private''.)

Note the vertical white bar in the center. In this example it shows that there are some source code differences (marked pink in the source) and how they compare to the other side. A blue "More" button at the bottom or top may indicate that you're not seeing all of the changes of this code. Clicking on it will scroll the source code up or down to make the next differences visible.

The small (<<) and (>>) buttons in the vertial white bar can be used to merge a single marked difference in the source code from one side to the other.

The Merge buttons merge the entire selected item to the other side.

In the above example, clicking the top left (<<) would change only the top left line's content from "Major" into "major", while leaving the other text differences intact. Clicking the "<- Merge" button instead would replace the entire left method source with the code from the right side.

Note that you can use Undo to revert your changes.

3.  Terms

PDEF

These are the "Property Definitions" that appear in Controls and Windows, such as a Window's Title and a Control's "TabStop" properties.

TLI

Short for Top-Level Item. Means the items of a project that appear in the Project tab, i.e. Classes, Modules, Windows, Menu Bars, FileTypes, Pictures, and so on. It does not include members of those items, i.e. Methods, Properties, etc.

4.  Hiding items

The Hide button hides selected items from the differences list. They can be unhidden by checking Show hidden - the hidden items will then appear in italics in the list.

Hidden items are remembered by their file names, their Locations (i.e. their name) and their right and left values. If any of the values changes later, the hiding is cancelled.

This makes it possible to filter out "confirmed" differences for later, making them only reappear if the item (e.g. method source) changes.

Note: If using the hierarchical list view, and an expandable item is selected when pressing the Hide button, then all its contained items will be marked for hiding. But only those items that will appear unter that item, not item that are currently filtered out using the view options. This means that the hiding only affects what you could currently see if you'd open all triangles.

5.  View options

You can view and filter the difference display in various ways. Some via the menu bar, others via checkboxes in the window:

5.1  Comparison Menu: Include Minor Differences

This option controls whether you want to only see the differences that affect the code of your program but not insignificant differences that often occur when saving the same project several times or in different project formats (the IDE is a bit flaky in this regard).

In particular, only if checked, the comparison will show the following kinds of differences:

• Case (upper/lower) differences in source code and notes (however, text in quoted strings, i.e. string literals, is not considered minor and will always be shown in the list).
• Different amount of white space in any text (includes values of string constants).
• The "UI State" items, i.e. the state of open tabs, window size etc.
• Added or missing default values of PDEFs (e.g. the infamous "TabStop" property that keep coming and going).
• Different representations of the same values (e.g colors: 0 vs &c000000, or booleans: False'' vs. empty value).

This option is persistent (i.e. it is remembered as a preference)

5.2  Comparison Menu: Top-Level Siblings Only

If checked, only those TLIs are shown that appear in both sides.

This is useful when you want to compare two separate projects which share common classes. Instead of getting listed all those items that unique to one of the projects, you only see those that appear on both sides. This usually includes the App class and any other top level items that share the same name.

This option is not persistent, it gets reset for every new comparison

5.3  Checkbox: Use Folders

If checked, the project items are shown in their respective folders, just like in the Real Studio IDE. If unchecked, folders do not show, and all their contents are listed at the root level of the list.

This option is persistent (i.e. it is remembered as a preference)

5.4  Checkbox: Hierarchical

If unchecked, each found difference is listed as one entry in a flat list. If checked, differences are hierarchically shown, based on their project container.

To open more than one level at a time, hold down the Option (Alt) key while clicking the expansion triangle or pressing the cursor right key.

This option is not persistent, it gets reset for every new comparison

6.  Comparing differently named items

If a method, class or similar item has been renamed between the two compared projects, these items will appear as two separate differences, as left only and right only. To get them lined up for comparison, select the two items in the upper left and right project items list and then choose Match selected items from the Comparison menu.

To select the two items, you have two options:

1. Select both their items in the difference list.
2. Select one item, then hold down the option (alt) key while clicking on the other item in the upper list.

7.  Caveats

• Here's a list of items that are currently not checked for differences (if you notice others please let me know):
  • Breakpoints

8.  Notes

• The Hide operation remembers the hidden items in a central file named IgnoredPairs.arbed, stored in the user's ApplicationSupport folder. The project for a set of hidden items is identified solely by its file name, without the path.