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.

This chapter explains how to start Merging, load it with files, and save the output file. The chapter is organized into the following sections:

• "Understanding Merging"

• "Starting Merging"

• "Working With Differences"

• "Merging Automatically"

• "Saving the Output File"

Understanding Merging

Merging loads and displays two text files for side-by-side comparison, each in a read-only text pane. Any differences between the two files are marked. A merged version of the two files, which you can edit to produce a final merged version is diaplayed.

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.

Figure 7-1 Merging Window With Loaded Files

The merged version contains two types of lines:

• Lines common to both input files

• Resolved differences

Starting Merging

To start Merging from the WorkShop main window, choose Tools > Merging.

Loading Files

To load files into Merging:

1. Choose File > Open.

2. 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.

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

4. 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.

5. 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.

6. Click Open to load the files.

   Figure 7-1 illustrates a loaded Merging window. 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.

Setting Merging Options

Use the Options menu 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

• Customize tab stops

• Set how white space and case differences are handled

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 glyphs 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 glyphs are highlighted.

Current, Next, and Previous Differences

The highlighted difference is called the current difference. The differences immediately before and immediately after are called the previous difference and the next difference.

Resolved and Remaining Differences

A difference is resolved if the changes to a line are accepted. A remaining difference is one that has not yet been resolved.

If the Auto Merge option is selected, Merging resolves differences automatically.

Understanding Glyphs

Glyphs help you understand the differences between files. There are three types of glyphs:

Glyph Type	Meaning
Plus sign (+)	New line
Minus sign (-)	Deleted line
Vertical bar (|)	Change in line
No glyph	No changes in line

When you designate a common ancestor file, glyphs next to the lines in each file indicate when the lines differ from the corresponding lines in the ancestor:

• If a line is identical in all three files, there is no glyph.

• If a line was added to one or both of the descendants, then a plus sign (+) shows where the line was added, and the line is highlighted.

• If a line is present in the ancestor but was removed from one or both of the descendants, then a minus sign (-) shows where the line was removed, and the line is highlighted and in strikethrough font.

• If a line is in the ancestor but has been edited in one or both of the descendants, then a vertical bar (|) shows where the line was changed, and the characters that differ are highlighted.

When a difference is resolved, the glyph changes to an outline font.

Moving Between Differences

You can move between differences using the buttons above the two panes or 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

To resolve a difference, accept the change in either the left or right pane:

1. To accept a difference, click the Accept button.

1. To accept the difference and move to the next difference, click the Accept & Next button.

   ---

   Note -

   When Merging is invoked by a Resolve transaction in the Configuring window of Sun WorkShop TeamWare, the Reload button is added to the Merging window. Clicking the Reload button at any point during resolution reloads the files, abandons all the conflicts that have been resolved, and starts over. The files are reloaded from disk, and any nonconflicting differences are resolved if the Auto Merge option is selected. You can then proceed by accepting one or the other version of the remaining lines that conflict.

   ---

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.

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. Changes could be the addition or removal of an entire line, or an edit to 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--either by choosing a line from a descendant, or by editing the merged file by hand.

When Merging automatically resolves a difference, it changes the glyphs 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 resolve the differences.

If you do not specify an ancestor file, Merging has no reference with 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.