|
EZ Merge: An Edit Tool for Merging Two or Three Files
What EZ Merge Is
EZ Merge provides a way to merge differences between two or three files (or sets of two or three files). It provides a single window with all the necessary information (list of differences, the files involved with the current difference highlighted in each file) shown in it with a point and click interface to provide basic merging functions (e.g., for a given difference, take what is different in the maintenance file and use it to replace what is different in the target file).
The 3-way merge provides a solution to the problem of maintaining released code (the Master file) by modifying it (in the Maintenance file) and adding the maintenance changes to the code being developed for the next release (the Target file). The 2-way merge provides function similar to ezdiff, but with a single window point and click interface. Except for differences between 2-way and 3-way merges, functions are similar between the two merges and, once one interface is learned, the other should be easy to learn.
Starting EZ Merge
EZ Merge may be invoked in three different ways. It may be invoked directly from EZ by clicking on menu items and specifying the file(s) to be merged. It may be invoked by editing a file created by saving the results of the menu item invocation (using the Save As menu item) or a file created by using a command line program, ezmrg.. Finally, it may be invoked directly by the ezmrg command line program using the -w parameter.
EZ Merge may be invoked from the EZ editor through menu items on the Ezmerge menu card. The 3-Way File Merge menu item allows three arbitrary files to be merged, and the 3-Way Directory Merge menu item allows a (possibly wild carded) list of files from three different directories to be merged. Similarly, the 2-Way File Merge menu item allows two arbitrary files to be merged and the 2-Way Directory Merge menu item allows a (possibly wild carded) list of files from two different directories to be merged.
When the 3-Way File Merge menu item is selected, you are prompted for a master file, a maintenance file, and a target file. The differences between those three files will be displayed, you can look at each difference, and, for each difference, change the target file to match either the master file or the maintenance file.
When the 2-Way File Merge menu item is selected, you are prompted for a master file and a target file. The differences between those two files will be displayed, you can look at each difference, and, for each difference, change either the target file or the master file to match the other file.
When the 3-Way Directory Merge menu item is selected, you are prompted for a master directory, a maintenance directory, a target directory, and a list of files (you may use wild cards). Only those files in the file list that exist in all three directories will participate in the merge. The differences for each set of files are shown and you can look at each difference, change the target file to match either the master file or the maintenance file, and do this to each of the sets of files represented by the files in the file list.
When the 2-Way Directory Merge menu item is selected, you are prompted for a master directory, a target directory, and a list of files (you may use wild cards). Only those files in the file list that exist in both directories will participate in the merge. The differences for each set of files are shown and you can look at each difference, change either the target file or the master file to match the other file, and do this to each of the sets of files represented by the files in the file list.
After a merge has been done, the differences can be saved using the Save As menu item on the File menu card. The resulting file can the be edited with the ez editor and the window will appear as it did originally.
Pop-up Menu Meanings
The Ezmerge menu card provides the following items:
3-Way File Merge: Selecting this menu item causes three file names to be prompted. These files are then compared for differences and the results displayed in the current ez window. To get this menu item to appear while editing any source or text file, add
addmenu ezmerge-create-files "Ezmerge~10,3-Way File Merge~1" textview
to your .ezinit file. To get this menu item to appear while in an EZ Merge window, add
addmenu ezmerge-create-files "Ezmerge~10,3-Way File Merge~1" filecmplistview
to your .ezinit file.
3-Way Directory Merge: This menu item prompts for three directories, a target directory, a maintenance directory, and a master directory followed by a prompt for a list of file names. The file names in the list may contain wild card characters and will be expanded against the target directory according to the C-shell wild card rules. Files in the expanded list that exist in all three directories will be compared and the differences for each set of files may be merged. To get this menu item to appearwhile editing any source or text file, add
addmenu ezmerge-create-list "Ezmerge~10,3-Way Directory Merge~5" textview
to your .ezinit file. To get this menu item to appear while in an Ezmerge window, add
addmenu ezmerge-create-list "Ezmerge~10,3-Way Directory Merge~5" filecmplistview
to your .ezinit file.
2-Way File Merge: Selecting this menu item causes two file names to be prompted for. These files are then compared for differences and the results displayed in the current ez window. To get this menu item to appear while editing any source or text file, add
addmenu ezmerge-create-files "Ezmerge~10,2-Way File Merge~10" textview
to your .ezinit file. To get this menu item to appear while in an EZ Merge window, add
addmenu ezmerge-create-files "Ezmerge~10,2-Way File Merge~10" filecmplistview
to your .ezinit file.
2-Way Directory Merge: This menu item prompts for two directories, a target directory and a master directory followed by a prompt for a list of file names. The file names in the list may contain wild card characters and will be expanded against the target directory according to the C-shell wild card rules. Files in the expanded list that exist in both directories will be compared and the differences for each set of files may be merged. To get this menu item to appear while editing any source or text file, add
addmenu ezmerge-create-list "Ezmerge~10,2-Way Directory Merge~15" textview
to your .ezinit file. To get this menu item to appear while in an Ezmerge window, add
addmenu ezmerge-create-list "Ezmerge~10,2-Way Directory Merge~15" filecmplistview
to your .ezinit file.
Note: Clicking on one of the above menu items from within an EZ Merge window causes a new buffer to be created. It does not cause the current Merge buffer to be updated even if the same files are entered in response to the menu items.
Sync Cursor Positions: Synchronizes the cursors in each subwindow based on the cursor in the subwindow with the input focus (the on where the title bar is reverse imaged).
If the cursor is between two differences the cursor will be placed between the same character in each window (or if the cursor is a selected region, the same characters will appear in the selected region in each window) and the windows will be scrolled such that the cursor (selected region) appears in each window. The last difference before the cursor position will become the current difference as indicated by the difference appearing in boldface type in the difference window.
If the cursor is within a difference (or, if a region has been selected and any part of the selected region falls within a difference), the difference will be selected just as if you had clicked on the difference in the difference window.
Treat Blanks as Equal/Don't Treat Blanks as Equal: Will remove (restore) all differences from the list of differences where the only differences between the three files are blanks (whitespace). For example:
Master contains:
if(a=b)
Maintenance contains:
if (a=b)
Target contains:
if (a = b)
would normally be shown as a difference between all three files. Clicking on Treat Blanks as Equal will cause this difference to be removed from the difference list because the lines are identical if the blanks are removed.
Note: While the difference is removed from the difference list, the difference number of the remaining differences (the number in the Diff Num column) does not change. Thus, gaps in the difference number sequence denote that one or more differences are not being displayed. Note that using one of these menu items just affects the display of differences and does not remove those differences from the total set of differences.
The initial setting of this menu item can be controlled by adding ShowBlankOnlyDiffs preference. The default is to display all differences where the only differences are blanks.
Hide/Show Non-Blank Diffs: Will remove (restore) all differences which are not caused only by whitespace differences. When merging source code, for example, Hide Non-Blank Diffs is useful for verifying that none of the blank only differences are in a string but only coding style differences. After Show Non-Blank Diffs has been selected, Treat Blanks as Equal can then be selected so that these differences can be ignored.
The initial setting of this menu item can be controlled by adding ShowNonBlankOnlyDiffs preference. The default is to display all differences where the only differences are blanks.
Note: The difference number of a given difference will not change as Hide/Show Non-Blank Diffs is selected. Hide/Show Target Only Diffs: Hides (shows) all differences where only the Target file is different (Master file and Maintenance file match). In those situations where the Target file already contains changes for a new release and you are trying to merge fixes into the new release, this is useful in narrowing the list of differences to just those where the Master and Maintenance files differ from the Target file. (Appears only on 3-way merges.)
Note: While the difference is removed from the difference list, the difference number of the remaining differences (the number in the Diff Num column) does not change. Thus, gaps in the difference number sequence denote that one or more differences are not being displayed.
The initial setting of this menu item can be controlled by adding a ShowTargetOnlyDiffs: No preferences file. The default is to display all differences where only the Target file is different.
Hide/Show Master Only Diffs: Hides (shows) all differences where only the Master file is different (the Maintenance and Target files are the same). Master only differences tend to indicate that new function has been added to both the Maintenance and Target files, thus making these differences of little interest. (Appears only on 3-way merges.)
The initial setting of this menu item can be controlled by adding a ShowMasterOnlyDiffs: No preferences file. The default is to display all differences where only the Target file is different.
Hide/Show Modified Diffs: Hides (shows) all differences where one of the files has been modified (all entries with a '>" in front of the difference number. This will allow you to quickly double check all differences that you haven't changed without having to go through all the differences that you already have changed.
General Note: The last five menu items are not orthogonal. Consider the following sequence of menu selections:
Hide Target Only Diffs
Treat Blanks as Equals
Show Target Only Diffs
The first selection removes all differences where the Master and Maintenance files are the same but the Target file is different. Of the remaining differences, the second selection removes all differences where the difference between the files are blanks. The last selection restores the difference window to the state it was in after the Treat Blanks as Equals was selected. Target only differences that differ only by blanks will not be shown until Don't Treat Blanks as Equals is selected.
Visit Target Buffer: Clicking on this menu item will cause the file in the Target buffer to replace the Merge buffer in the window. The target file can then be edited as it would in any ez window. You can return to the Merge buffer by clicking on Visit Buffer (^Xb) or Switch Buffer (^X^O) and entering "Merge", or by bringing up a Buffers subwindow and clicking on "Merge" in the Buffers subwindow.
Visit Master Buffer: Clicking on this menu item will cause the file in the Master buffer to replace the Merge buffer in the window. The master file can then be edited as it would in any ez window. You can return to the Merge buffer by clicking on Visit Buffer (^Xb) or Switch Buffer (^X^O) and entering "Merge", or by bringing up a Buffers subwindow and clicking on "Merge" in the Buffers subwindow. (Appears only on 2-way merges.)
The front menu card (the pulldown menu titled ez/ezmrg) will have the following menu items when you are using EZ Merge:
Save Target File: Clicking on this menu item causes the target file to be saved.
Save Master File: This menu item causes the master file to be saved (provided by default only on 2-way merges).
Optional Menu Items
Save Maintenance File: This menu item causes the maintenance file to be saved. Add
addmenu filecmplistview-save-maintBuffer "Save Maint~2" filecmplistview
to your .ezinit file and restart the ez session to get this menu item.
Save Master File: This menu item causes the master file to be saved. Add
addmenu filecmplistview-save-masterBuffer "Save Master~1" filecmplistview
to your .ezinit file and restart the ez session to get this menu item.
Note: The Save... menu items above should always be used to save the editable files. Even when input focus is in one of the editable subwindows, the Save menu item on the top (or ez) menu card will cause the EZ Merge data to be saved, not the file in the window with input focus. Using Save As and entering the file name of, for example, the target file, will cause the EZ Merge data to be saved in the target file, thus wiping out the target file.
The EZ Merge Window
When the 3-Way File Merge,2-Way File Merge, 3-Way Directory Merge, or 2-Way Directory Merge menu items are selected, the appearance of the ez window is changed. On the left hand side will be the list of differences in order of appearance in the files. This window is called the difference window.. At the bottom of the difference window are a set of buttons that provide a simple point and click method of performing common functions.
On the right will be two or three subwindows containing the master file, the maintenance file (only for 3-way merge), and the target file. These are editable subwindows. You must click in the window before you can edit the file in that window. The title bar of the window with the input focus will be reverse imaged. Note that for 3-way merges it will usually be the case that the master and maintenance files will be read-only so you will not usually be able to make changes to those files. Changes made to the target file after a merge has been done will not show up in the difference window until another merge is done again on the same files.
The Difference Window
The difference subwindow contains a list of the differences in order as they appear in the files and some buttons that provide a quick point and click method of performing common functions.
Each line in the difference window references one difference. The differences are numbered and the number of lines that are different for each file are displayed. The file(s) that are different have an asterisk (*) following the number of lines that are different for that file. Clicking on the line containing a difference highlights that difference by changing the characters to a boldface type, and the lines that are different in each of the three files are displayed in reverse image. If the target file has been changed so that it matches either the master or the maintenance file, a > sign will appear before the difference number and the line count for the file that the change came from.
At the bottom of the difference window is a set of seven buttons. The functions provided by six of these buttons are logically paired while the function of the seventh button is not.
Next Diff/Prev Diff buttons
These buttons may be used to go to the next difference (Next Diff) or the previous difference (Prev Diff).
Master->Target button
Replace the lines that are different in the current difference (the highlighted difference in the difference window) in the target file with the lines that are different in the master file.
Master->Maint button
Replace the lines that are different in the current difference (the highlighted difference in the difference window) in the target file with the lines that are different in the maintenance file.
This button appears only on 3-way merges.
Target->Master button
Replace the lines that are different in the current difference (the highlighted difference in the difference window) in the master file
with the lines that are different in the target file.
This button appears only on 2-way merges.
Next Set/Prev Set buttons
The next (previous) set of file differences may be selected by clicking on the Next Set (Prev Set) buttons. This will cause a new set of differences to appear in the difference window, and a new set of files to appear in the editable subwindows. These buttons are only useful for directory merges.
Restore Original button
If the target difference has been changed (Master/Maint->Target button has been pressed or the lines in Target file that make up the current difference have been edited), the original text, as it was at the time the merge was created, for the current difference can be restored by clicking on the Restore Original button. The Restore Original button will restore the original source in the target file at any time during this EZ Merge session., but only for the currently selected difference.
Note: For 3-way merges, all buttons (with the exception of Next/Prev Set buttons) operate on the current difference only and only affect the lines in the target file. Selecting one of these buttons will not affect the rest of the file
The Merge Buffer
When merges are created using the EZ Merge menu items, the EZ Merge window contains a buffer named Merge. Since it is a buffer, it supports the usual Buffer and Window menu card menu items and you can be visit other buffers using Visit Buffer on the Buffer card. More than one Merge buffer can be created and additional buffers will be named Merge-1, Merge-2, etc.
The buffer can also be saved. However, since there is no file name associated with the buffer, the Save As... menu item on the File card should be used to save the buffer. It is suggested that a .mrg file type be used. Once the file is saved, it can be edited and the EZ Merge window will appear.
If a .mrg file has been edited, however, the buffer name will be the same as the file name, e.g., foo.mrg, as is the case with other buffers containing data from a file. It will not be named Merge. Also, the Save menu item will now save the .mrg file, since the buffer is now associated with a file.
Buffers and EZ Merge
Since one can easily visit other buffers, it is easy to modify or delete buffers that are participating in the EZ Merge. Since marks[1] are used to mark where differences are, editing the data in the buffer will not affect where the differences show up. But using Delete Buffer and Switch File both cause the deletion of the buffer[2] and if the buffer is participating in an EZ Merge, when the Merge buffer is revisited the subwindow that contained the data in the buffer that was deleted will be blank. This can also occur if you do a Refresh Buffer to a different file[3]. Clicking on one of the differences or one of the buttons will cause the data to reappear in the window.
Usage Hints:
Definitions:
Master file: This file is the file that contains the released source code. Normally it is read-only.
Maintenance file: This file contains the "fixes" to the released code (the Master file).
Target file: This is the file that corresponds to the "new release" code. It normally is the file that you want updated with the changes in the maintenance file.
Given the above definitions for a 3-way merge, one is primarily interested in those differences where the Maintenance file only is different (indicated by a '*' next to the number of lines different in the Maint Lines column in the difference window) and those differences where all 3 files are different (indicated by '*'s next to the numbers in all three columns in the difference window). Maintenance file only differences indicate changes that have been made as a result of the fix, and, in general, one should be able to be add these fixes to the Target file by clicking on the Maint->Target button.
Target file only differences (indicated by a '*' next to the number of lines different in the Target Lines column in the difference window) indicate where function has been added for the new release. Master file only differences (indicated by a '*' next to the number of lines different in the Master Lines column in the difference window) indicate places where the fix has already been applied to the new release code. Therefore, you may wish to temporarily remove Target file only differences and Master file only differences from the difference list by clicking on the Hide Target Only Diffs and Hide Master Only Diffs menu items.
Differences where all three files are different indicate that new function has been added in the target release and the same code had to be fixed in the released code. You will have to pay special attention to these differences.
Differences that only differ by blanks are often caused by inconsistent coding styles and so may also be of little interest. The menu item Treat Blanks As Equal will remove those differences that differ only by blanks. However, for source code, at least one case is of interest. If the added/deleted blank is within a character string, the difference may be significant. The Hide Non-Blank Diffs menu item may be used to remove all differences that are not caused by blanks. The remaining differences may then be quickly scanned for those that are caused by blanks within character strings and appropriate changes made. Then use Show Non-Blank Diffs to get the differences back that are different because of non-blank characters and use Treat Blanks As Equal to remove the blank only differences since they have already been checked.
As you get more comfortable using EZ Merge, the above techniques should allow you to eliminate many of the uninteresting differences and speed up the process of merging the important differences.
As mentioned above, 2-way merges are based on ezdiff function. Thus, even though one subwindow is labeled the Master: it is considered to be a writeable file. This is the reason for the Target->Master button appearing for 2-way merges. It is good practice, in general, to consider the Master file as if it is read-only. There are cases, however, where it is meaningful to change both files; thus, the availability of the Target->Master button.
How EZ Merge Works
EZ Merge takes three files and runs gdiff3 against them. Gdiff3 compares three files providing information as to where differences exist, whether or not all files are different, and, if not, which file is different; which lines are different for each file; and whether or not a line is added. EZ Merge then takes the output of gdiff3 and uses it to build the list of differences in the left hand window. For 2-way merges, the Target is also used as the Maintenance file but this is transparent the user. Using the same compare program for both 3-way and 2-way compares allows optional functions, like detecting blank only differences, to operate the same way for both 2-way and 3-way merges.
Customizing EZ Merge
Proc Table Entries
The following procs can be added to your ~/.ezinit file and can be used to access the button functions through keystrokes. Placing the procs in your ~/.ezinit file will take effect when you bring up an EZ Merge window through ez. They will also take effect in your ezmrg -w window provided you include your ~/.ezinit file in your ~/.ezmrginit file.
filecmplistview-previous-difference- same as Prev Diff button
filecmplistview-next-difference- same as Next Diff button
filecmplistview-master-into-target- same as Master->Target button
filecmplistview-maint-into-target- same as Maint->Target button (3-way merge only)
filecmplistview-previous-compare- same as Prev Set button
filecmplistview-next-compare- same as Next Set button
filecmplistview-restore-original- same as Restore Original button
Example of binding one of the above procs to a key sequence in your ~/.ezinit file:
addkey filecmplistview-previous-difference ^X^P filecmplistview
The following proc is tied to menu items, but not keystroke sequences:
filecmplistview-save-targetBuffer- saves the Target buffer
The following procs are not tied to menu items, but are available if you find that you need the capability:
filecmplistview-save-maintBuffer- saves the Maintenance buffer
filecmplistview-save-masterBuffer- saves the Master buffer (this is provided as a menu item for 2-way merges)
Example of binding one of the above procs to a menu item in your ~/.ezinit file.
addmenu filecmplistview-save-maintBuffer "Ezmerge,Save Maint Buffer~15" filecmplistview
Preferences
The following preferences affect the operation of EZ Merge windows
ez.ShowBlankOnlyDiffs: yes
If no is specified, differences that are a result of whitespace (blanks, tabs, and newline characters) will not be shown when the EZ Merge window comes up. The Don't Treat Blanks as Equal menu item will appear.
ez.ShowOnlyNonBlankDiffs: yes
If no is specified, differences that are not a caused by white space (blanks, tabs, and newline characters) will not be shown. The Show Non Blank Only Diffs menu item will appear.
ez.ShowTargetOnlyDiffs: yes
If no is specified, differences wherein the Master and the Maintenance files are the same are not shown. The Hide Target Only Diffs menu item will appear.
ez.ShowMasterOnlyDiffs: yes
If no is specified, differences wherein the Target and the Maintenance files are the same are not shown. The Hide Master Only Diffs menu item will appear.
ez.DiffListWidth: 40
Determines the percentage of total horizontal window width that the left-hand column (containing the list of differences, and buttons) should take up. The default is 40%, leaving 60% for the master/maint/target files in the right-hand column.
Error Messages
Various error conditions will cause messages to appear on the message line. For example, if a non-existent file name is entered on 3-Way File Merge, a message "Unable to read file xxx.C" is issued. We have tried to make these error messages self-explanatory and diagnostic of the true problem.
When a .mrg file is created the full path names of the files participating in the merge, their sizes and their date/time stamp is saved as part of the .mrg file. When the .mrg file is edited, the current size and date/time stamp of each file is checked against the saved size and date/time stamp. If any of these do not agree, and error message is given indicating the problem and that the merge should be redone. However the EZ Merge window will come up using the data from the .mrg file as is.
Warnings
The only way to save the files in the editable subwindows is through the menu items, Save Master File, Save Maintenance File, and Save Target File. Do not try to save a file in one of the subwindows using Save As and typing in the name of the file while you have an EZ Merge buffer in the window. If you do so, you will overwrite the file you were trying to save with the merge data.
The Restore Original button will not work if the original data within the difference in the target file contain insets. This is not a problem with source code since source code cannot contain insets, only for those types of files that can contain insets, like text files. Master->Target and Maint->Target buttons will work correctly even if insets are contained within the region that is copied.
Related Topic
|
