Sun WorkShop TeamWare: User's Guide: 4 - Introduction to Merging

# Introduction to Merging | # 4 |

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

Differences Defined | page 36
Graphical Overview | page 37

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

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.

## Graphical Overview

The graphical interface for Merging consists of one main window, in which you do most of your work, and pop-up windows for handling files and setting properties. Descriptions of the graphical interface are found in the online help. Pull down the Help menu on the upper right of the Merging menu bar to access Help Contents.

### Merging Window

The Merging window at startup shows 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.

### 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 merged, 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 in the Properties window. 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.