Chapter 4 Introduction to Merging

This chapter deals with the basic concept of Merging files, and is organized into the following sections:

• "Differences Defined"

• "Merging Window"

For explicit details on using Merging, together with an example, see Chapter 13, Starting Merging and Loading Files."

Merging loads and displays two text files for side-by-side comparison, each in a read-only text pane. Merging marks lines that differ between the two files and displays a merged version in a third text pane. When automatically activated, the merged version contains two types of lines:

• Lines that are common to both input files (these lines always appear in the output file)

• Marked lines that are different in each file (these lines appear as the result of the default automerge process)

You can edit the merged version and save it as an output file.

At the time you load the two files to be merged, you can also specify a third file, called the ancestor of the two files (which are called its descendants). When you have specified an ancestor file, Merging marks lines in the descendants that are different from the ancestor and produces a merged file based on all three files. To automatically merge (automerge) the two input files, you must specify an ancestor file.

Differences Defined

Merging operates on differences between files. Although you probably have a good intuitive grasp of what a difference is, the following describes how Merging recognizes and classifies differences.

Difference

When Merging discovers a line that differs between the two files to be merged (or between either of the two files and the ancestor), it marks with glyphs the lines in the two files. Together, these marked lines are called a difference. While Merging is focusing on a difference, it highlights the glyphs.

Current, Next, and Previous Difference

The difference on which Merging is focusing at any given time is called the current difference. The difference that appears immediately later in the file is called the next difference; the difference that appears immediately earlier in the file is called the previous difference.

Resolved and Remaining Difference

A difference is resolved if either you or Merging accept the changes to a line. Differences are resolved one of two ways:

• While focusing on a difference, you can accept a line from one of the original files, or you can edit the merged version by hand. When you indicate that you are satisfied with your changes (by clicking on a command button), the current difference is then resolved.

• If the Auto Merge feature is on, Merging resolves differences automatically. For more information on how Merging resolves differences, see the discussion in "Merging Glyphs".

After a difference is resolved, Merging identifies it by changing its associated glyphs from solid to outline font. Merging then automatically advances to the next difference (if the Auto Advance property is on) or moves to the difference of your choice.

A remaining difference is one that has not yet been resolved.

Merging Window

The graphical interface for Merging consists of the Merging window, in which you do most of your work.

Merging Window at Startup

Figure 4-1 shows the Merging window with the left and right text panes at the top displaying the files to be compared; the text pane at the bottom displays a merged version of the two files that you can edit.

Figure 4-1 Merging Window at Startup

File menu	Provides commands for opening and saving files
Edit menu	Provides commands for managing differences between files
Navigate menu	Provides commands for moving among differences in both files
Option menu	Provides commands for setting merging, scrolling, display, and diffing options
TeamWare menu	Provides command for starting other TeamWare tools
Tool bar	Provides quick access to file management operations
Status field	Displays information about the state of your merge
Child pane	Shows the child file with markings
Command buttons	Provide quick access to navigating and editing functions
Parent pane	Shows the parent file with markings
Merged Result pane	Shows you the combined file with markings
Merging message area	Displays messages about operating in the Merging window

Merging Glyphs

When files are loaded in the text panes, glyphs appear to indicate the disparities. There is a difference between two files being merged without a common ancestor, and two files that have a common ancestor (this case is actually a three-way merge). The meaning of the glyphs in each case is slightly different, as explained below.

Two Input Files

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

• If two lines are identical, no glyph 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.

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

Three Input Files

When an ancestor file has been specified for the two files to be merge, lines in each descendant are marked according to their relationship to the corresponding lines in the common ancestor:

• If a line is identical in all three files, no glyph 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.

• 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 and in strikethrough.

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

Resolved differences are marked by glyphs in outline font.

Table 4-1 summarizes the automerging algorithm. Ancestor is the version of a text line that is in the ancestor file; Change 1 is a change to that line in one of the descendants; Change 2 is another change, different from Change 1. Only when a line is changed differently in the left and right descendants does automerging fail.

Table 4-1 Automerging Rules Summary

Left Descendant	Right Descendant	Automerged Line
Ancestor	Ancestor	Ancestor
Change 1	Ancestor	Change 1
Ancestor	Change 2	Change 2
Change 1	Change 1	Change 1
Change 1	Change 2	No Automerge

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 automatic merging by deselecting Auto Merge on the Options menu. When automatic merging is disabled, Merging constructs a merged file using only lines that are identical in all three files and relies on you to 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 automerge 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 and relies on you to resolve differences.