Installation Integrating MergeRight with other version
control and configuration management tools
MergeRight
Features and Benefits
Two Way vs. Three Way Comparisons
Two way comparisons
If you already have a copy of MergeRight installed on one system, installation is as easy as copying the MergeRight directory and files to another system. Or if you don't have a copy, you can get a self-expanding archive from our website: http://www.mergeright.net/, which also gives instructions for how to unpack the file and run the installer.
Once installed, the program is capable of running immediately in Personal Edition mode. This mode will allow you to do merges on files of less than 100 lines. To enable your system Professional Edition mode capable of merging larger files, you'll need to get a license key.
You can purchase MergeRight by contacting our sales department at Sales@prescient.com. Once your payment is confirmed, you will be sent a license key to enable production use. To install your license just find the "License.mr" file in your MergeRight program directory. Edit it with a text editor such as NotePad and delete the existing license keys and replace them with the license keys you have been sent in the mail.
Once you have installed MergeRight and configured your license key, you are ready to run MergeRight. If you start it without specifying files to work on, it will bring up a dialog box and ask you for files to merge. It will actually remember the last files you were working on -- but if you have never used MergeRight before, don't worry. MergeRight comes with a set of demo files preloaded that allow you to explore how MergeRight works. Or go ahead and enter in your own files and just start working.
Windows Users
As a windows application, you start it the way you would any
other windows application, you click on the MergeRight menu item in the Start / Programs
menu, then find the exe file, and you either double click it, or "open" it with
the right button menu. When started this way, MergeRight will start by displaying the file
specification panel, letting you choose which files you want to Merge. Start shortcuts can
be created that actually are configured to pass parameters, if you are so inclined.
DOS Users
You can also run the program as a DOS application. This
means that it can be run from a Batch command file (.bat) or from another program -- this
makes integration with other version control and configuration managers easy. MergeRight
allows these existing files to be reused, so they don't have to be typed in by hand.
UNIX Users
Make sure the java runtime environment and java executable
are in your executable path. Then use the MergeRight shell program to run MergeRight.
DOS and UNIX Users
Passing parameters is easy. At the command line, you can set
options and pass the names of files to the MergeRight program by adding parameters to the
MergeRight command.
mergeright
with no filenames, MergeRight will launch with a file specification panel to allow you to choose the files you want to merge.
mergeright -compare
When the optional -compare switch is set, the visual difference is shown, but no result files will be saved. This is most often used in conjunction with other version control or configuration management tools when they want to prevent the result file from being saved.
mergeright -multi cmdfile
When the optional -multi switch is set, the following parameter, cmdfile, is the name of a file which contains a list of several file sets to compare. This is useful if you want to merge all the files in two parallel directories, or several related checked out files. The format of the command file if it exists is one or more lines, each of which has 1, 2, 3, or 4 filenames, as below. The program will then create a separate main window for each set of files.
mergeright file.MRG
When only one file is passed, MergeRight assumes the file is a MRG file. MRG files keep intermediate results of merges that are saved while they are in progress. This is useful if you begin a merge and want to stop before you have resolved all differences, but want to resume where you left off at a later time, or if you want to review a merge you did earlier.
mergeright leftfile rightfile
When mergeright is passed two files, it does a two-way comparison on the files. No recommendations can be made when two-way comparisons are done. The result file name is unspecified, so if the user attempts to save the result they will be queried for the file name to use for the result file.
mergeright leftfile rightfile -result resultfile
Does a two way comparison on the files and sets the initial name of the result file to resultfile.
mergeright ancestorfile leftfile rightfile
Does a three-way comparison, allowing recommendations to be made. The result file name is unspecified, so if the user attempts to save the result they will be queried for the file name to use for the result file.
mergeright ancestorfile leftfile rightfile resultfile
Does a three-way comparison, making recommendations, and sets the initial name of the result file to resultfile.
mergeright ancestorfile leftfile rightfile -result resultfile
Does a three-way comparison, making recommendations, and sets the initial name of the result file to resultfile.
You can see from the command line interface and from the visual interface that MergeRight only merges two files at a time. In the original MergeRight design, support for merging more than two files at a time was contemplated, however, early tests showed that when there were three or more merge files on the screen at a time that human cognitive capabilities quickly become over taxed. Users would keep losing their place and forgetting which file component they wanted to include or exclude. As a result merge accuracy plummeted and merge times took longer.
Because of the cognitive load effects, merging 3 or more files visually consistently took longer than merging two of the files and then merging the 2 way result with the 3rd file, and so on.
Because reduced human performance times and improved accuracy of the results are our primary goals at MergeRight, we no longer support merging more than 2 files at a time in the current interface, and we recommend people who must merge more than 2 files to do so in the two at a time fashion described in the previous paragraph. For those who remain skeptical that this is in fact faster and more accurate, contact us and we'll tell you how to run your own tests to see for yourself.
MergeRight has been designed so that it can be easily integrated with various version control and configuration management systems. The command line options (parameters) follow standard conventions supported by most version control and configuration management systems, so that MergeRight can be automatically invoked whenever a merge needs to take place. For configuration management systems like Tower Concept's Razor or Perforce, MergeRight is an ideal add on, providing merge capability where there was none.
For other configuration management systems which include merge tools (such as RCS or Clearcase) MergeRight is often used to replace the existing merge capabilities which lack MergeRight's innovative and more productive user interface. In many cases, replacement is as simple as renaming and replacing the existing merge tool with the MergeRight executable or alias (symbolic link). In other cases, a simple 3-5 line shell script can handle checking out necessary versions, starting MergeRight and checking in the result file upon completion
To use MergeRight with a check out / check in system, just check out the ancestor and the merge files as read only copies in the file system. Then invoke MergeRight. When MergeRight is complete, check out the branch end file as a editable copy and then replace it with the MergeRight result file and check in the new file. If you need consulting services to implement this for you, contact Sales@prescient.com and we will help you find someone to integrate MergeRight into your system.
In addition to formal version control and configuration management systems. Many people use naming schemes where versions identifiers are included in the file name, or directory name. Sometimes these are as simple as appending "-old" or "-new" to a filename, or appending a version number (v5) or date (14feb98). Whatever your scheme, if it is easy to describe it should be easy to write a simple shell script or bat file to automate use of MergeRight with it.
If you have already used MergeRight you probably already know how easy it is to learn and use, and how it helps you to avoid errors during the merge process. You may not know how it accomplishes all this, but if it works, you may not care. So feel free to skip this section. But if you are just one of those people who are curious about everything, or you would rather read about MergeRight than actually use it, here are some comments on what MergeRight can do, and what makes it different (and we think better) than other merge tools. Finally, we'll invite you to make up your own mind and to see for yourself.
MergeRight can help you do two things: compare two files and merge them.
Comparing files just means looking at how the files differ from each other or from a common ancestor. As such it is a completely nondestructive activity. Because MergeRight uses a "concordance" view mechanism, it is always easy to see what is the same in both files and what is different. From menu items inside the View menu you can hide all the common areas so you can focus on just the differences, or if you prefer, hide all the difference areas and show only what is the same. Color coding in 3 way comparisons (explained below) make it easy to tell whether a passage is different because something was added, or because something was deleted, or because something was replaced. Menu items inside the GoTo menu, as well as the next and previous diff buttons allow you to quickly move between changed sections.
Merging files also doesn't change any of the files being compared, but it does generate a new file, the merged result. MergeRight has a number of options that can be invoked from the View menu which allow you to quickly select or deselect sections to include in your merged result.
When comparing two files you can easily tell if a section appears in one file but not the other. But when you see this, you can't tell why the two files differ. Was the section added to the first file, or was it deleted from the second. We can't tell. But often knowing is critical to deciding whether to include the section in a merged result or not. If the section was a new feature, we probably want it included. But if deleting the section was done to fix a bug, we sure don't want to include it again.
A common way to tell whether material was added or deleted is to compare to the original file that both are derived from. If the section isn't in the ancestor, it must have been added. On the other hand, if it was in the ancestor it must have been explicitly deleted.
To determine this, instead of just doing one comparison, we must do three. If we are doing three, it is important that we do them as quickly as possible and generate the minimum number of differences if possible. MergeRight uses an implementation of an algorithm developed by Webb Miller and Eugene Myers. Myers has done a mathematical proof that this algorithm most quickly reaches solutions with the minimum number of differences and that no faster algorithm is possible. The Unix file merge command and several others use inferior merge algorithms that can take very long times to process some files and may make more difference sections..
By doing three way comparisons we can actually make recommendations about which code to include in the merge: Things that were deleted should not be included, and things that were added or changed should be included.
Sometimes changes are made to the same lines in both files being merged. When this happens, we say the sections are "in conflict". We can't make a recommendation for that section. Only by looking at the sections in conflict can the user determine semantically how to "resolve" the differences. Often this can be done by copying the changes from each file and pasting them together in the result file. Sometimes it is more complicated and you have to select one side, the other side, or edit right there and create something entirely new. This is sometimes hard to do with other Merge tools, but not with MergeRight. Color coding and menu items make it easy to find conflicts, and the built in editor makes it easy to copy, paste and even edit in place, before the final merge is generated.
Because of conflicts, it is usually impossible to merge without some editing. Traditionally there have been two types of approaches.
The first approach, typified by non-visual merges (sometimes called "automatic" merges), attempts to apply recommendations automatically and create a merged result file with no user intervention. If there are conflicts, these are flagged with "comments" in the resulting file and by a printed warning. If there are no conflicts things are presumed to be fine (though this can be erroneous as we explain below). When there are conflicts the user then edits the result file with a text editor and looks for the conflict comment markers and then edits the sections between them until they are okay. This is called the Merge/Edit strategy because first you Merge and then you Edit.
The other approach, used by MergeRight and most other visual merge tools, does the comparisons, but does not commit the merge until the user had a chance to edit any conflicts and to detect and fix any semantic conflict problems that may occur.
Theoretically Merge/Edit would be faster because except in conflict cases no human intervention is needed. Unfortunately, automated merges introduce hard to detect problems in a small but important number of cases. Moreover, finding these kinds of problems after the merge has taken place is very hard because there is no longer information in the result file that allows you to tell what changed. For this reason, Edit/Merges are strongly preferred when accuracy is a concern.
When doing three way merges, MergeRight can make recommendations as to which sections to include or exclude. Usually these recommendations are right, but merges should always be checked to make sure that there are no "semantic" conflicts introduced by the merge process.
While these happen rarely, when they do happen if they are not detected before the result file is written, they introduce subtle hard to find and fix bugs. For this reason, MergeRight's user interface has been designed to improve the capabilities of users to find and fix these semantic conflict problems before they get into the final merge result file.
This is a big difference between MergeRight and other so called "automatic" merges. Those automatic merges automatically apply all the recommendations and don't provide you a way to detect that this will introduce errors or a way to fix them. MergeRight, on the other hand makes it easy to use these defaults but also easy to override them on a case by case basis where ever semantic conflicts are found.
The following is just a brief overview. For more complete information on this topic, see our web site or contact sales@prescient.com.
Consider the following example:
Imagine that each gray area represents many lines of code
that are common in each file. If we do an automatic merge we will get the following result
file.
However, when this program runs it won't result in k = 10. Instead the resulting program will have k = 100, even though none of the merge files had that result, and even though no syntactic "conflict" was detected by the automated merge.
Our example is greatly simplified for illustrative purposes, but such semantic errors introduced by automated merges, while rare, still happen with enough frequency and therefore automated merge results must always be carefully checked.
One important way our example has been simplified is that we have used an ellipsis to compress many lines of code into one. With our example, it would be relatively easy to see that the conditions were occurring that could cause a semantic error, and to correct it even if you were looking only at the result file. And with some comparison tools it would join the 4 differences into 2 8-line conflicting difference areas, so you would be alerted to check the file.
But as the size of the file increases, large common areas can separate each change and it may be hard to see the semantic conflict. This quickly overwhelms "automated merges" and even overwhelms users of most other visual merge tools, as you can't hide the common areas. With MergeRight we realize that putting the changes close together so you can see several of them at a glance could be just what makes it possible to perceive a semantic conflict. So with MergeRight, common areas are typically "hidden" by default or through the use of a hide button or menu item. Hiding reduces them down to a single line marked with an ellipsis, just as in our example above. Clicking the ellipsis button or using a menu item allows you to expand the common area and see it for context, after you've already checked for possible semantic conflicts. This greatly increases the ability of the user to spot and prevent semantic errors from being introduced during the Merge process.
Another advantage to the MergeRight user interface is the use of the concordance style view. By "concordance", we mean that corresponding sections from each file are always shown side by side, as in our example above.
MergeRight does this on a section by section basis, whereas other visual merge tools only have whole files side by side in a "continuous" file view fashion. This means that with other merge tools you have to keep unlocking and relocking the scrollers so that corresponding sections of each file are visible at the same time. With MergeRight, corresponding sections are automatically kept side by side, so there is no need to lock files to keep corresponding parts next to each other. This results in faster and more accurate decision making when reviewing merge recommendations.
We are proud to say that MergeRight was the first and only merge tool to use the powerful concordance style view. It is far harder to program than the continuous style systems -- but far easier on the user.
Many merge tools use symbols (e.g. "=", "+", and "-") to indicate which sections were the same and which were deleted. Some use other symbols like "<" and ">" to indicate changes that were in one file or the other when using these tools. It is important to know these things, for otherwise code that was removed intentionally to fix a bug might be accidentally re-inserted in the result file. Unfortunately, symbol processing and symbolic interpretations is a relatively high cognitive load activity. This slows assessment and degrades correct resolution of merge differences.
This applies to more than just merge tools. We respond faster to a red light in a traffic signal than we can to the letters "stop". In fact, we observed that with symbolic merge tools people often misread or ignored the symbols thus introducing errors. With MergeRight, we used colors that are recognized and correctly processed without symbolic interpretation demands on the mind. In fact, we used habits such as color matching in our recommendation mechanism to further encourage people to correctly handle explicitly deleted sections.
Our use of the concordance style view, color matching, ellipses and many other user interface details all reflect our particular view of what a merge tool should be. Until a merge tool can be made smart enough to automatically resolve all conflicts, both syntactic and semantic, humans will need to intervene in and review the merge process. We realize that what is most important is to make the human as effective and productive as possible, not to make our programmer's job easier. That means focussing on what humans can do well and enabling them to do it with as little confusion or distraction as possible. And it also means focussing on what kinds of activities overload human cognitive tasks and finding ways to minimize those problems. The means to implement these improvements is through the user interface, and at Prescient that has been our main focus.
You'll see the difference just by using MergeRight and doing a head to head test. You'll see why our first release received a cover notice in SunWorld, and why early customers like Lockheed and Loral found that new MergeRight users learned the tool in 15 minutes and were outperforming experienced users of other merge tools in just an hour. You'll see why Tandem concluded the tool paid for itself in reduced merge time in just two weeks, and in reduction of merge introduced bugs in hours. But don't take our word for it. Run a comparison test yourself. We're convinced that when you are done that you too will agree that finally there's a programming tool that respects human capabilities and limitations: MergeRight.
Write us with your own test results. We always want to know how we are doing at making each use a little more productive. Send your comments to our chief technical officer: mcgregor@prescient.com.
