Introduction to Sun WorkShop

Chapter 7

Merging Source Files

Merging lets you compare two text files, merge two files into a single new file, and compare two edited versions of a file against the original to create a new file that contains all new edits. Merging loads and displays two text files for side-by-side comparison, each in a read-only text pane. Any difference between the two files is marked. A merged version of the two files, which you can edit to produce a final merged version, is displayed.

When you load the two files to be merged, you can also specify a third file from which the two files were created. When you have specified this ancestor file, Merging marks lines in the descendants that are different from the ancestor and produces a merged file based on all three files.

For more information, see the online help (choose Help Contents in the Merging window to access online help).

Loading Files into Merging

Load files into merging by following these instructions:

1. Choose Tools Merging from the WorkShop main window.

The Merging window opens (see FIGURE 7-1). The Merging window is divided into three panes: two side-by-side panes, which display different versions of the file, and the merged result in the bottom pane. The top two panes are read-only, the bottom pane contains selected lines from either or both versions of the file and can be edited to produce a final merged version.

2. Choose File Open.

3. In the Directory text box, select a working directory.

This is the default directory used to select and save files. The browse button to the right of the text box displays a dialog box in which you can select a directory.

4. In the Left File and Right File text boxes, select the two files you want to compare.

5. If you are comparing the files against a common ancestor, type the earlier version of the two files in the Ancestor File text box.

An ancestor file is required to use Auto Merge.

6. If you want to specify the name of the output file, type it in the Output File text box.

The name filemerge.out is the default, and the file is stored in the working directory.

7. Click Open to load the files.

The names of the left file, right file, and output file are displayed above each text pane. In a three-way comparison, the name of the ancestor file is displayed in the window header.

FIGURE 7-1   Merging Window

Working With Differences

Merging operates on differences between files. When merging discovers a line that differs between the two files to be merged (or between either of the two files and an ancestor), it marks the lines in the two files with icons corresponding to how the lines differ. Together, these marked lines are called a difference. As you move through the files from one difference to the next, the lines that differ and their icons are highlighted.

The highlighted difference is called the current difference. The differences immediately before and immediately after are called the previous difference and the next difference. A difference is resolved if the changes to a line are accepted. A remaining difference is one that has not yet been resolved.

Reading Merging Icons

To help you find differences more easily, Merging highlights lines that differ with color and icons. Yellow shows an addition, red shows a change, green shows a deletion.

The meaning of icons is different if you are comparing two versions with each other (two input files), or if you identify an ancestor for the two versions of the file (three input files).

Two Input Files

When only two files have been loaded into Merging, lines in each file are marked by icons to indicate when they differ from corresponding lines in the other file:

• If two lines are identical, no icon is displayed.
• If two lines are different, a vertical bar (|) is displayed next to the line in each input text pane, and the different characters are highlighted in yellow.
• If a line appears in one file but not in the other, a plus sign (+) is displayed next to the line in the file where it appears, and the different characters are highlighted in red.
• Resolved differences are marked by icons in outline font.

Three Input Files

When you load two files to be merged, you can also specify a third file, called the ancestor of the two files. An ancestor file is any earlier version of the two files. When you identify an ancestor file, it is used as a basis to compare the two files and automatic merging can be done. Merging marks all lines in the derived files or their descendants that differ from the ancestor and produces a merged file based on all three files.

The lines in the files that are different from the ancestor file are marked with change bars and colors. Here's what each means:

• If a line is identical in all three files, no icon is displayed.
• If a line is not in the ancestor but was added to one or both of the descendants, a plus sign (+) is displayed next to the line in the file where the line was added, and the different characters are highlighted in yellow.
• If a line is in the ancestor but has been changed in one or both of the descendants, a vertical bar (|) is displayed next to the line in the file where the line was changed, and the different characters are highlighted in red.
• If a line is present in the ancestor but was removed from one or both of the descendants, a minus sign (-) is displayed next to the line in the file from which the line was removed, and the different characters are highlighted in green and in strikethrough.
• Resolved differences are marked by icons in outline font.

Moving Between Differences

You can move between differences using the buttons above the two panes or through the Navigate menu. Use the Previous and Next buttons to scroll through the differences without accepting them. Choose Navigate Find to navigate to a particular text string. Choose Navigate Goto Line to navigate by line numbers.

You can also navigate between differences by using the popup menu that is available in the Child and Parent panes. Click the right mouse button in either pane to open the menu.

Resolving Differences

Accept the change in either the left or right pane to resolve a difference. To accept a difference, do one of the following:

• Click the Accept button to accept the difference.
• Click the Accept & Next button to accept the difference and move to the next difference.

For more information, see the online help (choose Help Contents in the Merging window to access online help).

Setting Difference Options

Choose Options Diff Options to customize merging to ignore certain kinds of differences between files. You can set merging to ignore trailing or embedded white space and to ignore differences in case.

For more information, see the online help (choose Help Contents in the Merging window to access online help).

Merging Automatically

Merging can resolve differences automatically, based on the following rules:

• If a line has not changed in all three files, it is placed in the output file.
• If a line has changed in one of the descendants, the changed line is placed in the output file. A change could be the addition or removal of an entire line or an alteration to some part of a line.
• If identical changes have been made to a line in both descendants, the changed line is placed in the output file.
• If a line has been edited in both descendant files so that it is different in all three files, no line is placed in the output file. You must decide how to resolve the difference, by either choosing a line from a descendant or by editing the merged file by hand.

When merging automatically resolves a difference, it changes the icons to outline font. Merging lets you examine automatically resolved differences to be sure that it has made the correct choices.

You can disable Auto Merge by choosing Options Auto Merge. When automatic merging is disabled, the output file contains only the lines that are identical in all three files. You must then resolve the differences.

If you do not specify an ancestor file, merging has no reference to which to compare a difference between the two input files. Consequently, merging cannot determine which line in a difference is likely to represent the desired change. The result of an auto merge with no ancestor is the same as disabling automatic merging: Merging constructs a merged file using only lines that are identical in both input files. You must resolve the differences.

Saving the Output File

Save the output file by clicking the Save button or choosing File Save. The name of the output file is the name you specify in the Output File text box.

To change the name of the output file while saving, choose Save As and fill in the new file and directory names in the Save As dialog window.

Setting Merging Options

Use the Options menu in the Merging window to set various merging options. The menu items enable you to:

• Create a merged version of the files automatically
• Control whether files scroll separately or by corresponding lines
• Control if line numbers or line ends are displayed
• Customize tab stops
• Set how white space and case differences are handled

For more information, see the online help (choose Help Contents in the Merging window to access online help).