Sun WorkShop TeamWare: User's Guide: 16 - Examining Differences

# Examining Differences | # 16 |

This chapter further explains some features and presents an example of how to use Merging. The chapter is organized into the following sections:

Moving Between Differences | page 189
Resolving Differences | page 189
Automatic Merging | page 190
An Example | page 190

## Moving Between Differences

You can navigate through differences using either the Next and Prev buttons or the up arrow and down arrows. Merging automatically moves to the next difference immediately after you resolve the current difference.

## Resolving Differences

A difference is represented by a blank line in the merged (output) file in the lower text pane. To resolve a difference, you edit the line displayed there by either:

- Accepting the line displayed and incorporate it into the merged file by choosing either the Accept or Accept & Next button over the side you wish to accept.

- Editing the line in the merged file by hand, and marking the difference as resolved. From the Edit menu, choose Mark Selected as Resolved.

## Automatic Merging

If you have loaded a common ancestor file, Merging is often able to resolve differences automatically, based on the following rules:

- If a line has not been changed in either descendant (it is identical in all three files), it is placed in the merged file.

- If a line has been changed in only one of the descendants, the changed line is placed in the merged 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 merged file.

- If a line has been changed differently in both descendant files so that it is different in all three files, Merging places no line in the merged file. You must then decide how to resolve the difference--either by using a line from the right or left file, or by editing the merged file by hand.

## An Example

This example merges two files that have a common ancestor. The files are `file_1` and `file_2`, and the ancestor file is named `matriarch`. The descendant files `file_1` and `file_2` were derived from `matriarch` by editing. The edits show all varieties of changes that could occur in the descendants: deleting lines, adding new lines, and changing lines.

The content of each line in the example helps to identify whether or not it was changed, and how. The ancestor file contains only twelve lines and is shown in Code Example 16-1.

Merging does not number lines in the files it loads; the numbers are part of the example text and were placed there for clarity.

Code Example 16-1 Ancestor File (`matriarch`)

    1 This line is deleted in file_1
    2 This line is in all three files
    3 This line is deleted in file_2
    4 This line is in all three files
    5 This line is in all three files
    6 This line is changed in descendants
    7 This line is in all three files
    8 This line is changed in descendants
    9 This line is in all three files
    10 This line is changed in file_2
    11 This line is in all three files
    12 This line is in all three files

Code Example 16-2 shows the contents of `file_1`. This file is identical to `matriarch` with the following exceptions:

- The line numbered 1 in the `matriarch` file was deleted in `file_1`.
- A new line was added following the line numbered 4.
- The line numbered 6 was changed (a different change was made to this line in `file_2`).
- The line numbered 8 in the `matriarch` file was changed (an identical change was made to this line in `file_2`.)

  Code Example 16-2 Descendant File (`file_1`)

      2 This line is in all three files
      3 This line is deleted in file_2
      4 This line is in all three files
       &&& Added to file_1 &&&
      5 This line is in all three files
      6 This line is modified in file_1 from matriarch
      7 This line is in all three files
      8 #&# Changed in file_1 and file_2 #&#
      9 This line is in all three files
      10 This line is changed in file_2
      11 This line is in all three files
      12 This line is in all three files

Code Example 16-3 shows the contents of `file_2`. This file is identical to `matriarch` with the following exceptions:

- The line numbered 3 in the `matriarch` file was deleted.

- The line numbered 6 was changed (a different change was made to this line in `file_1`).

- The line numbered 8 was changed (an identical change was made to this line in `file_1`).

- The line numbered 10 was changed (no change was made to this line in `file_1`).

- A new line was added following the line numbered 11.

  Code Example 16-3 Descendant File (`file_2`)

      1 This line is deleted in file_1
      2 This line is in all three files
      4 This line is in all three files
      5 This line is in all three files
      6 This line is altered in file_2 from matriarch
      7 This line is in all three files
      8 #&# Changed in file_1 and file_2 #&#
      9 This line is in all three files
      10 ### Changed in file_2 ###
      11 This line is in all three files
       ### Added to file_2 ###
      12 This line is in all three files

To simplify the example, we place all three files in one directory, and use this directory as the working directory where we will start Merging.

### Starting Merging

| Go to the directory in which `matriarch`, `file_1`, and `file_2` are stored. Type the following to start Merging in background mode and load the three files:
    demo% filemerge -a matriarch file_1 file_2 &

Merging starts up with the Auto Merge feature turned on by default. The window that appears displays an automerged output file.

In the upper left of the window, Merging has reported finding seven differences, of which only one remains unresolved--six differences were resolved by automerging, and are marked by glyphs in outline font.

The meaning of the glyphs is as follows: a vertical bar means a change in the marked line, a plus sign signifies a line added, a minus sign means a line was deleted. Unresolved states are marked by solid glyphs, unresolved by outline. These glyphs are highlighted in color except when the color map is full. The default significance is: red indicates a change, green indicates a deletion, yellow shows an addition.

The unresolved difference (line 6) is marked by a vertical bar.

### Examining Differences

Merging highlights the unresolved difference, which it identifies as the line numbered 6 in `file_1` and `file_2`. When differences are being resolved with Merging, the resulting Merging window (`filemerge`.`out`) shows the current state of the file with automatic merging.

Proceed to the next difference by choosing the down arrow above the appropriate file, or Navigate: Next Difference. The next difference becomes the current difference.

Proceed through the differences by clicking on the down arrow.

Auto Merge preserves a change that was made to one file if no change was made in the other file.

When a difference has not been resolved by Auto Merge, as indicated by the solid highlighted glyph next to the lines involved in the difference, you need to resolve the difference by making a choice. The vertical line indicates that the line has been changed (as opposed to added or deleted). In this case, Auto Merge failed because the same line was changed differently in the two files, and Merging could not decide which change was more valid.

You could resolve this difference in one of the following ways:

- Click on the Accept, Accept & Next button on the left to place the line from `file_1` into the output file.
- Click on the the Accept, Accept & Next button on the right to place the line from `file_2` into the output file.
- Edit the output file by hand.

##### Editing the Output File

To edit the output file, move the pointer into the output file's text pane and place it in the line you want to change. In this example, the following line was typed in:

    >>> This line edited by hand <<<

Choose the Edit:Mark Selected as Resolved. This menu item marks the difference as resolved. In this example there are no more unresolved differences, so the next difference remains the current one.

Note that the message in the upper left part of the window now indicates that all differences have been resolved. Nevertheless, proceed to verify the automerged differences.

Continue through the differences by clicking on the down arrow.

The final difference results from a line that was added only to `file_2`. Merging places the new line in the output file just as it did when a new line was added to `file_1`, which resulted in the third difference.

### Saving Output File

Now that all differences have been resolved and the automerged differences verified, you can save the output file. The output file takes the name shown in the Load Files pop-up window, which by default is `filemerge`.`out.`To write the file, choose Save from the File menu, or the Save button. To save the file under another name, use Save As, from the File menu.