Main Window Titlebar
Menubar
Toolbar
Concordance Panel Info
bar File Specification Window Important Terms In this section we describe the major visual features of MergeRight and define some important terms.
Main Window
Titlebar
Menubar
Toolbar
Concordance Panel
Info
bar
File Specification Window
Important Terms
Most of the time when you are using MergeRight you'll be in a "Main Window". This is where all the action takes place, where you can see the comparisons of the files you are merging and control what is included and what is not. If you are doing multiple merges or comparisons, each one takes place in a separate Main Window.
The main window is constructed of 5 major components
stacked one below another:
Titlebar
Menubar
Toolbar
Concordance Panel
Info
bar
Detailed information on each component is given in their sections below.
The Titlebar identifies the window. The MergeRight label lets you know that this is a MergeRight main window. There is a MRG file which corresponds with every main window which keeps track of the merge work in progress. Normally this file has the same base name (ResultFile) as the result file (if one has been specified), but has the MRG extension. The name of this MRG file is indicated in the titlebar. Since the base name is derived from the result file, this will help you identify which main window to work on if you have multiple main windows visible.
Most commands in MergeRight can be reached from the
Menubar. There are 5 menus:
File
Edit
View
GoTo
Help
Each menu is described in more detail below.
The File menu is used to specify new files to merge, to open an existing MRG file, to save your results to a result file, or to print either your result file or your concordance.
This menu also provides access to the Registration Key, the file that validates your software for use.
The items on the File menu are:
New..
Open...
Save
Save As...
Print...
Registration Key
Close
Exit
This menu item brings up the file specification window and allows you to specify new files you want to compare or merge. From the file specification window you can specify the two branch files to compare or merge, a common ancestor if there is one, and a result file that you want to save the results to.
The last set of file specifications you used are pre-set in the dialog box, and your recently merged files are stored as alternatives, or you can type in names directly or use a file browser to choose the files you want.
This menu item is not enabled in this release. It is reserved for future releases.
When enabled, selecting this menu item will output the result file. If you have not already specified a result filename, you will be prompted to specify the name and location the first time you select this menu item.
There are a number of situations when this item will appear grayed out, and will be inactive:
When this item is selected, a panel is raised that allows you to specify a result file name and path. If saving this result file is allowed at this time, you will have the choice of saving the result file immediately. If the -compare parameter is set or the unresolved diffs remain, the user will not be allowed to save the result file now and must cancel the save operation.
The Choose button will raise a file selection dialog.
This menu item is not enabled in this release. It is reserved for future releases.
This menu item is not enabled in this release. It is reserved for future releases.
When the Close menu item is pressed, If the -compare parameter is set the main window is closed without saving Result file..
If the result file has been saved and no changes have been made since then, this main window is closed.
Otherwise, if
all sections are
resolved but some have changed since the last save, or
a result file has never
been saved,
then the user gets a dialog that asks them if they want to save the Result file before closing.
Goes through the close procedure for all open Main WIndows, and then closes the application.
When this item is enabled, press it to undo the last action. When not enabled there is no current undoable action and the menu item is grayed out.
After an undo operation is done, the Redo item will be enabled. Clicking will redo the last undone operation.
Use this menu item (or the keyboard equivalent Ctl-X) to copy the highlighted text to the clipboard and then delete it.
Use this menu item (or the keyboard equivalent Ctl-C) to copy the highlighted text to the clipboard without deleting it.
Use this menu item (or the keyboard equivalent Ctl-V) to paste the text on the clipboard to the current location of the I-bar cursor.
Use this menu item to raise the Find/Replace dialog box.
The Find menu allows you to find a string in one of your branch files. You can limit the search, so you can search only the left branch, only the right branch, only sections in common, or only difference sections. You can even limit your search to difference sections that are selected for resolution or those which are not.
This flexability makes it easy to to find strings used in multiple places, which can increase your chances of finding and preventing semantic conflicts.
You can also replace any found string with another, further simplifying the repair of conflicts using the replace mode.
Undoes all resolutions, selections and text edits, returning the window to its initial state.
Disabled in this version, it is reserved for setting Toolbar Preferences in a future release. In this release there are no preferences that apply to Toolbars.
When you select one side of a difference block for inclusion in the final result file, we call that resolving the difference. You can resolve and unresolve difference blocks on a case by case basis. But you can also operate on many of them at a time, using options in the View menu. For instance, a good strategy to use is to check the file in unresolved mode to make sure there are no semantic conflicts. Then resolve (and edit if necessary) any syntactic or semantic conflicts. Then use Select Recommended to resolve all the remaining differences.
Because the select menu items only apply selections to unresolved differences, it is also easy to use them to select just one or two items from one branch file and then select the rest of the difference blocks from the other. This is a useful technique for only including some new features from one branch file, or even for "backing out" selected features.
Use the Deselect All menu to discard all your difference resolutions and return to their initial unresolved (side by side) state.
Use Select Left Diffs to resolve all the remaining unresolved differences using the left branch file. This command will not override any already resolved differences, so if you already have resolved some sections using the right branch, these resolutions will not be lost.
A common way to use this function is to manually select a few right branch differences and then take all the rest of the differences from the left side using Select Left Diffs. This will allow you to create a new version that is identical to the left branch with a couple of changes.
This menu item works identically to clicking on the LeftFile button on the Toolbar.
Use Select Right Diffs to resolve all the remaining unresolved differences using the right branch file. This command will not override any already resolved differences, so if you already have resolved some sections using the left branch, these resolutions will not be lost.
A common way to use this function is to manually select a few left branch differences and then take all the rest of the differences from the right side using Select Right Diffs. This will allow you to create a new version that is identical to the left branch with a couple of changes.
This menu item works identically to clicking on the Right File button on the Toolbar.
Use Select Recommended to resolve the remaining unresolved differences using the recommended diff. This command will not override any already resolved differences, so if you already have resolved some sections using the non-recommended branch, these resolutions will not be lost.
A common way to use Select Recommended is to quickly resolve all the non-conflicting changes. Then use the next Unresolved Diff and Previous Unresolved Diff buttons to quickly find all the conflicts. Manually select one side or the other editing, cutting and pasting as necessary until you have resolved all the remaining diffs. You can quickly reach the merged result this way.
Most of the time, Common areas do not require much attention in merging, and in fact their interposition between difference areas can help hide semantic conflicts. Use Hide All Common to reduce all common areas to a small ellipsis button ("..."). To expand them again, use Expand All Common.
If you want to read your file in a what you see is what you get (WYSIWYG) fashion, expand all the common areas with the Expand All Common menu button. When you are done, hide them again with Hide All Common.
If you are more interested in seeing what is the same in the two files you are comparing, use Hide All Diffs, to minimize the Diff areas to a small ellipsis button ("..."). When you are done, use Expand All Diffs to see them again.
If you have hidden Diff areas, use the Expand All Diffs menu item to return them to their expanded state.
At each point in time, one of the common or diff blocks currently is selected for edit. To change which one to edit, you can just click on it. But if the item you want to edit is off screen you will want to quickly find it, bring it into view and move the edit focus there. The GoTo Menu items (along with the GoTo buttons on the tool bar) let you do this quickly.
The Go To Previous Diff menu item (and corresponding button on the toolbar) will move the focus to the previous diff block (regardless of whether it was resolved or hidden). If this block is not currently visible, the window will scroll automatically to place it at the top of the page. If you are at or before the first diff block, this item will be disabled.
The Go To Previous Unresolved Diff menu item (and corresponding button on the toolbar) will move the focus to the previous unresolved diff block (regardless of whether it was hidden). If this block is not currently visible, the window will scroll automatically to place it at the top of the page. If you are at or before the first unresolved diff block, this item will be disabled.
If you have used Select Recommended, this menu item (or toolbar button) provides an easy way to find all the remaining unresolved (in conflict) areas.
The Go To Previous Hidden Diff menu item will move the focus to the previous hidden diff block (regardless of whether it is resolved). If this block is not currently visible, the window will scroll automatically to place it at the top of the page. The block will NOT be expanded. If you are at or before the first hidden diff block, this item will be disabled.
The Go To Previous Expanded Diff menu item will move the focus to the previous expanded diff block (regardless of whether it is resolved). If this block is not currently visible, the window will scroll automatically to place it at the top of the page. If you are at or before the first expanded diff block, this item will be disabled.
The Go To Next Diff menu item (and corresponding button on the toolbar) will move the focus to the next diff block (regardless of whether it is resolved or hidden). If this block is not currently visible, the window will scroll automatically to place it at the top of the page. If you are at or after the last diff block, this item will be disabled.
The Go To Next Unresolved Diff menu item (and corresponding button on the toolbar) will move the focus to the next unresolved diff block (regardless of whether it is hidden). If this block is not currently visible, the window will scroll automatically to place it at the top of the page. If you are at or after the last unresolved diff block, this item will be disabled.
If you have used Select Recommended, this menu item (or toolbar button) provides an easy way to find all the remaining unresolved (in conflict) areas.
The Go To Next Hidden Diff menu item will move the focus to the next hidden diff block (regardless of whether it is resolved). If this block is not currently visible, the window will scroll automatically to place it at the top of the page. The block will be expanded. If you are at or after the last hidden diff block, this item will be disabled.
The Go To Next Expanded Diff menu item will move the focus to the next expanded diff block (regardless of whether it is resolved). If this block is not currently visible, the window will scroll automatically to place it at the top of the page. If you are at or after the last expanded diff block, this item will be disabled.
The Go To Previous Common menu item will move the focus to the previous common block (regardless of whether it is hidden). If this block is not currently visible, the window will scroll automatically to place it at the top of the page. If you are at or before the first common block, this item will be disabled.
The Go To Previous Hidden Common menu item will move the focus to the previous hidden diff block . If this block is not currently visible, the window will scroll automatically to place it at the top of the page. The block will be expanded. If you are at or before the first hidden common block, this item will be disabled
The Go To Previous Expanded Diff menu item will move the focus to the previous expanded common block. If this block is not currently visible, the window will scroll automatically to place it at the top of the page. If you are at or before the first expanded common block, this item will be disabled.
The Go To Next Common menu item will move the focus to the next common block (regardless of whether it is hidden). If this block is not currently visible, the window will scroll automatically to place it at the top of the page. If you are at or after the last common block, this item will be disabled.
The Go To Next Hidden Common menu item will move the focus to the next hidden diff block . If this block is not currently visible, the window will scroll automatically to place it at the top of the page. The block will be expanded. If you are at or after the last hidden common block, this item will be disabled
The Go To Next Expanded Diff menu item will move the focus to the Next expanded common block. If this block is not currently visible, the window will scroll automatically to place it at the top of the page. If you are at or after the last expanded common block, this item will be disabled.
You've found the MergeRight Help menu item already because this is how you launch this help tool from MergeRight. Help contains information on how to get get started with MergeRight, a visual glossary of all the components, and task based help aimed at answering those "How do I...?" questions.
If you want to check for new releases of MergeRight, information about known problems and solutions, or other information about MergeRight not included in this help, click on MergeRight WebPage to launch your local browser and reach our webpage.
If you want to Contact Prescient Software to send us comments, complaints or kudos, click on this menu item. This menu item will launch your mailer and give it our email address. write your comments, click send and your message is off to us right away.
To find out information about which release you have, use the About MergeRight menu item to display our About panel.
Use the Left File Button to resolve all the remaining unresolved differences using the left branch file. This command will not override any already resolved differences, so if you already have resolved some sections using the right branch, these resolutions will not be lost.
A good way to use this feature is to manually select a few right branch differences and then take all the rest of the differences from the left side using Left File Button. This will allow you to create a new version that is identical to the left branch with a couple of changes.
This menu item works identically to clicking on the Select Left Diffs menu item.
The Go To Previous Unresolved Diff button (and corresponding go to menu item) will move the focus to the previous unresolved diff block (regardless of whether it is hidden). If this block is not currently visible, the window will scroll automatically to place it at the top of the page. If you are at or before the first unresolved diff block, this button will be disabled.
If you have used Select Recommended, this button (or menu item) provides an easy way to find all the remaining unresolved (in conflict) areas.
The Go To Previous Unresolved Diff button (and corresponding go to menu item) will move the focus to the previous unresolved diff block (regardless of whether it is hidden). If this block is not currently visible, the window will scroll automatically to place it at the top of the page. If you are at or before the first unresolved diff block, this button will be disabled.
If you have used Select Recommended, this button (or menu item ) provides an easy way to find all the remaining unresolved (in conflict) areas.
Edit Button
One text area always has the edit focus. This is the one where edits take place. Next and previous items are calculated from this item. Scroll vars on the text area show which one is editable. Changing which edit area is editable is simple as clicking in it. Sometimes however ou may want to turnoff editing on the text area and just read it. Use the Edit button to do so. Press the button again to return to edit state.
The Go To Next Diff button (and corresponding menu item) will move the focus to the next diff block (regardless of whether it is resolved or hidden). If this block is not currently visible, the window will scroll automatically to place it at the top of the page. If you are at or after the last diff block, this button will be disabled.
The Go To Next Unresolved Diff button (and corresponding menu item) will move the focus to the next unresolved diff block (regardless of whether it is hidden). If this block is not currently visible, the window will scroll automatically to place it at the top of the page. If you are at or after the last unresolved diff block, this buton will be disabled.
If you have used Select Recommended, this button (or menu item) provides an easy way to find all the remaining unresolved (in conflict) areas.
Use Right File Button to resolve all the remaining unresolved differences using the right branch file. This command will not override any already resolved differences, so if you already have resolved some sections using the left branch, these resolutions will not be lost.
A good way to use this feature is to manually select a few left branch differences and then take all the rest of the differences from the right side using Right File Button. This will allow you to create a new version that is identical to the left branch with a couple of changes.
This menu item works identically to clicking on the Select Right Diffs menu item.
The Concordance Panel is the heart of MergeRight. It is where the comparisons of the two files are shown side by side, and it is where you resolve differences to create a merged result file.
The Concorance Panel contains a series of alernating Diff blocks and Common blocks. These blocks always alternate. Common follows Diff and Diff follows Common block like this:
Common blocks have two visible states. In their normal state, the common text is hidden, showing only an expand button ("...") on the left side, like this:
In the alternate state, which can be reached by clicking on the expand button, the common text is expanded, and a hide button ("...") is shown on the right, like this:
Clicking on the hide button causes the text to be hidden again.
In the hidden text state, the left side is an Expand
Button marked with an ellipsis. Clicking this button causes the common block to switch
to the expanded text state.
In the expanded text state, the left side displays the common text. To edit the text, just click it.
In the expanded text state, the right side is an Expand Button marked with an ellipsis. Clicking this button causes the common block to switch to the hidden text state.
Like common blocks, Diff Blocks have two main states, hidden and expanded.
The hidden state looks much the same as the common block hidden state, though it can be distinguished by two arrow buttons on the right:
In addition to being hidden or expanded , a diff block has another state: whether it is resolved left, resolved right, or unresolved.
The resolution state can be determined by looking at the two arrow buttons. If neither button is highlighted, then the difference is unresolved -- that is neither side has been selected yet for the merged result.
Alternatively if the right arrow button is highlighted, the diff block is resolved right -- that is the selection on the right will be incluided in the merged result.
Similarly for the left arrow button.
Both buttons cannot be selected at the same time. If you click on a selected button, the diff block switches back to the unresolved state.
In the expanded state, the contents of the left side varies as well. In the unresolved state, you can see both the left and right diff blocks side by side:
In the Resolved Right state, only the right text block is visible, like this:
And in the Resolved Left state, only the left text is visible, like this:
When in the Unresolved state, the Left Text is displayed in the left part of the divided diff text portion of the block block.
When in the Resolved Left state, the Left Text occupies the entire text portion of the block .
In the Resolved Right state, the left text is not shown.
When in the Unresolved State, the Right Text is displayed in the right part of the divided diff text portion of the block block.
When in the Resolved Right state, the Right Text occupies the entire text portion of the block .
In the Resolved Left state, the Right Text is not shown.
The Hide Button occupies the left most of the 3 buttons on the right side of the diff block. Click it to hide the diff block text.
The Resolve Left button is the middle button of the 3 buttons on the right side of the diff block. The button is a toggle button and switches between the Resolve Left state and the unresolved state. When in the Resolve Left state, the button is highlighted.
The Resolve Right button is the right most button of the 3 buttons on the right side of the diff block. The button is a toggle button and switches between the Resolve Right state and the unresolved state. When in the Resolve Left state, the button is highlighted.
The Expand Button is visible whenever the diff block is in the Hidden state. When visible, it appears as an ellipsis button ("...") and occupies the left hand side of the diff block. Clicking the buttton causes the diff block to switch to the Expanded state.
When a three way comparison is done, MergeRight can make recommendations about which diff blocks to include in the merged result. Where no syntactic conflict occurs (that is, where only one side was changed), the side that was changed is marked recommended by using the teal colored background. The non-recommended side, that is the side which was unchanged, is rendered on a gray background.
For instance, in this example, we can see that the RightFile contained a change and the left file diff was the same as the ancestor, resulting in a teal right side, and a gray left side.
When you want to select one side for inclusion in the merged result, just press the corresponding Resolve Left or Resolve Right button. For instance, in this example the right side has be selected. We can see this because only the text from the Right branch file has been displayed and the selected Resolve Right button is displayed in its highlighted state.
When code has been deleted, it will be missing in one side and visible in the other side of the concordance. You can tell a deletion from an addition when doing a three way comparison, because the empty side will be the recommended side. Here the Right branch file deleted text that was in the ancestor.
When code has been added, it will be missing in one side and visible in the other side of the concordance. Empty blocks of code are displayed with cross hashing to distinguish them from blank lines in the file. You can tell an addition from a deletion when doing a three way comparison, because the non-empty side will be the recommended side. Here the Left branch file added text that was not in the ancestor.
When code has been replaced, there will be text on both sides of the concordance. If only one side was changed, you will be able to tell which side by the recommendation color. Here the Right branch file modified text that was in the ancestor.
When both sides have changed from the ancestor there is a syntactic conflict, and no recommendation can be given. In this situation, both sides have the gray background color
If one side has been added or the other side deleted, there will be one side which has text and the other will be empty.
Sometimes one side was changed, but all that was added was one or more blank lines.
From time to time MergeRight has various non-urgent messages that it displays to you to give you hints as to what buttons do, and to confirm actions. These hints and messages are shown in the Info bar area at the bottom of the window.
Hints are short messages that describe what the buttons or fields your cursor is pointing at to are for. To learn the purpose of a control, just place the cursor over it and a short hint will be displayed in the Info bar.
If MergeRight needs to tell you about the progress of any operation you selected, this information or aconfirmation upon completion message will be displyed in the Info bar area. For instance, when you change the number of resolved or unresolved differences the message window may display: "6 unresolved differences out of 42", leting you know how many more resolutions need to be done before the result file can be saved.
When you start MergeRight, if you have not specified a set of files to compare, you will be displayed a file specification window. This window is also displayed when you click New... or Open... in the File menu.
The panel remembers the most recent files used in a merge, so it is easy to reuse them if you just need to re-merge a file.
The ancestor file is optional. If specified, the comparison will be a three way comparison with regards to the ancestor. This allows the system to give recommendations as to which changes to select. Click the choose button if you need to browse the file system for a file before specifying it.
Enter the first of the branch files to compare here. Click the choose button if you need to browse the file system for a file before specifying it.
Enter the second of the branch files to compare here. Click the choose button if you need to browse the file system for a file before specifying it.
The result file is optional. If unspecified, the result file will default to UntitledNN, where NN is a unique number. The base name of the result file is used as the base name work in progress (MRG) file except that the MRG file has the .MRG prefix.
Ancestor
File Arguments,
Parameters
Branch File
Common Compare and Merge
Concordance Conflicts: Semantic and Syntactic Registration Key Demo
Files Diff
Ellipsis
Expand Hide
Merge File, MRG File, Work In Progress file
Recommendation Resolve, Resolved Diff, Unresolved Diff
Result
FileWhen two files are derived simultaneously from the same file the original file is considered the Ancestor file of the two branch files
Arguments, also called Parameters, are additional command line instructions which tell MergeRight which files to use as branch files, and optionally as the ancestor or results file.
When two files derive from the same ancestor and are compared, each of the two derived files are called Branch files.
When two files are compared, sections that are the same in both files are said to be "in common".
In a Merge there are two stages. The first stage is comparison, in which each file is broken into smaller pieces, alternating sections of common and differences. The second stage is the Merge stage in which the resulting differences are resolved and then woven back together to form a new result.
We call MergeRight's special view of the interleaved common areas and side by side difference areas a Concordance View.
When changes in two files make it impossible to merge files safely without human intervention, we say that there are differences that are In conflict. Specifically, we speak of of syntactic conflicts whenever a section is different in each of the branch files, and each branch file section is also different from the same section in the underlying Ancestor file. When both sections have been changed from the ancestor like this, we cannot make a recommendation and the user must resolve the conflict manually.
We also consider the case where there are no syntactic conflicts, but in which changes between different diffs in the same file will yield erroneous differences as a "semantic conflict". MergeRight's use of ellipses in Common areas helps you spot these syntactic problems.
When Prescient Software has verified your payment, it will give you a registration number. Use this to configure MergeRight so that you can use MergeRight in Professional Edition mode, not merely in Personal Edition mode.
MergeRight ships with a set of practice demo files that you can use to practice with MergeRight before using it on your own valuable files. These demos files have been developed in connection with the MergeRight Help system, and can be used to train yourself how to use the program.
When comparing two files, if there are sections which are not the same, the section is called a Diff section.
An Ellipsis ("...", plural: Ellipses) means that something has been hidden. In MergeRight, ellipsis buttons are used h to hide and later expand individual sections.
When an Ellipsis is "Expanded" the corresponding common section is shown as readable text.
Sometimes text areas are shown as just an ellipsis button. These sections are said to be "hidden".
When two branch files are being changed, but their changes do not conflict, we can recognize which side has been changed. A recommendation suggests which file changed with respect to the common ancestor. It is recommended that this changed side be the resolved side. Usually by resolving according to recommendations you will get all the changes included and thus achieve the desired result of the merge process.
When two branches have a difference section, and one side has been chosen to be in the result file we say that section has been "resolve"d, and that the resolved section is called a "Resolved Diff" setion. Where neither file has yet been selected for inclusion in the result file yet, we say that the difference section is an "Unresolved Diff" section.
When a merge is completed and all differences have been "resolved", the saved resolutions version can be saved as the Result File.
