Chapter 7. Comparing and Merging Files Graphically with xcleardiff

The previous chapter discussed file comparison and merge operations. This chapter describes the graphical diff/merge utility, xcleardiff, in more detail. The main topics are:

For a discussion of the actual file comparison and merge algorithms, see the diff and merge manual pages.

Summary

xcleardiff is a graphical diff and merge utility for text files. (It implements the xcompare and xmerge methods for the predefined element types text_file and compressed_text_file.) xcleardiff can also compare, but not merge, directory versions.

On color display monitors, xcleardiff uses different colors to highlight changes, insertions, and deletions from one or more contributing files. During merge operations, input files are processed incrementally and, when necessary, interactively, to visibly construct a merged output file. You can edit the merged output as it is being built—either directly in the merged output display pane, or with an arbitrary text editor—to add, delete, or change code manually, or to add comments.

xcleardiff is implemented with a standard window system toolkit. See your window system documentation for a description of general mouse and keyboard conventions.

Invoking xcleardiff

You can invoke xcleardiff directly from the command line, specifying files or versions to compare or merge. However, because xcleardiff implements the xcompare and xmerge methods for the text_file_delta and z_text_file_delta type managers, the following cleartool subcommands, when applied to text files, also invoke xcleardiff:

  • xdiff

  • xmerge

  • findmerge (with options -xmerge or -okxmerge)

The xdiff, xmerge, and findmerge commands include the advantage of some extra command options—optional ClearCase preprocessing—in the same way that diff and merge offer more flexibility than direct calls to the character-based cleardiff utility. xdiff -pred, xmerge -insert, and findmerge -ftag are all examples of commands that perform useful ClearCase processing before invoking xcleardiff.

You can also invoke xcleardiff using xclearcase buttons and menu options:

  • file or vtree browser menubar: Versions -> Diff and Versions -> Merge

  • file or vtree browser toolbar: Diff button (see Figure 7-1) and Merge button (see Figure 7-2).

    Figure 7-1. Diff Button


    Figure 7-2. Merge Button


Setting Your Color Scheme

The ClearCase GUI utilities support several predefined color schemes, which are collections of X resource settings. ClearCase schemes are stored in the directory /usr/atria/config/ui/Schemes. (A special scheme, Willis, is designed for use with monochrome monitors.)

You can specify a scheme in your standard X resources file (typically $home/.Xdefaults) with a line like:

*scheme: Monet

See the schemes manual page for more details.

You can also use standard X Window System mechanisms to customize the xcleardiff display window. The X class name is xcleardiff or Diff. The following color-related resources are specific to graphical diff and merge operations:

xcleardiff*promptBrightColor
                           (highlight prompt and current diff (default: yellow))
xcleardiff*changeColor
                 (highlight change relative to base contributor (default: blue))
xcleardiff*deleteColor
                 (highlight deletion relative to base contributor (default: red))
xcleardiff*insertColor
             (highlight insertion relative to base contributor (default: green))

Comparing Files

As you study the examples in this chapter, keep in mind that there are usually several ways to accomplish the same thing.

Example 1: Compare with Predecessor

Let's compare versions of a file element. The most common comparison operation is to diff the version selected by your view with its predecessor version.

  1. Open the desired directory in a file browser as shown in Figure 7-3 and select the element, util.c for example.

    Figure 7-3. File Browser with File Element util.c Selected


  2. Press the Diff button (see Figure 7-1) .

    This button (as explained in its “pop-up help”, accessible with rightMouse) compares the version selected by the current view with its direct predecessor. Figure 7-4 shows the resulting output.

    Figure 7-4. Graphical File Comparison


The following command line and the Diff button are equivalent.

% cleartool xdiff -predecessor util.c

The menu item Versions -> Diff -> Selected vs. predecessor provides a third path to the same result.

Base Contributor File

The base contributor file is the first file specified (first on the command line or selected first in a browser) and is displayed on the left of the screen. All other contributors are compared against the base file.

Text Line Annotations

By default (that is, unless line numbering is enabled), the following annotations can appear in the annotation panes:

Insert 

Line occurs in this file, but not in base contributor file. (Insertions default to green on a color display monitor.)

Delete 

Line occurs in base contributor file, but not in this file. (Deletions default to red on a color display monitor.)

Change 

Line has changed from the base contributor file to this file. (Changes default to blue on a color display monitor.)

****** 

Empty lines, introduced to keep corresponding source lines aligned when files are displayed side-by-side.

The Options Menu

Show Line Numbers 


Enable/disable line number annotations for all lines of all contributor files.

Stack Vertically 


Enable/disable vertical stacking of the difference panes. Side-by-side is the default.

The View Menu

base-file  


Enable/disable display of the base file. Typically, you want to see the base file during a diff operation, but probably do not need to see it during a merge.

contributor-1 ... 


Enable/disable display of this contributor file.

Display Lock Icon

You can scroll difference panes independently or synchronously. Each difference pane has a lock/unlock toggle button. If vertical and/or horizontal scrollbars are active, all locked panes scroll together. An unlocked pane can be scrolled independently. Whenever you press Previous Diff or Next Diff, the difference panes all resynchronize with the base file. You cannot unlock the base file.

Example 2: Comparing Arbitrary Versions of an Element

The Versions -> Diff submenu (and the xdiff command) lets you compare any combination of versions (including three, or even more, simultaneously). Suppose you wanted to compare the version of util.c selected by your view with /main/1, instead of its immediate predecessor:

  1. Select util.c from a file browser.

  2. Choose the menu item Versions -> Diff -> Selected vs. other...
    A vtree browser (Figure 7-5) comes up and prompts you for the (older) version to compare with the selected version of util.c.

    Figure 7-5. Vtree Browser Prompting for a Version to Compare


Click on version 1 to select it, and then press the Ok button. A Cleardiff window appears, like the one in Figure 7-4, but with different versions this time.

The command line equivalent for this merge operation is:

% cleartool xdiff util.c@@/main/1 util.c

Comparing Directories

You can compare directory versions as well as file versions (see Figure 7-6.) Use the following procedure to compare two versions of a directory element, neither of which is selected by your current view.

  1. Select the directory icon from a file browser.

  2. Choose Versions -> Diff -> Other vs. other...

  3. In the prompting vtree, supply the “older” version and press Ok. Then supply the “newer” version and press Ok.

    Figure 7-6. Comparing Directory Versions


The equivalent command line is:

% cd /vobs2/rell4/src; cleartool xdiff .@@/main/1 .@@/main/2

Merging Files

As we did for file comparison, let's start with a common operation.

Example: Merging from a Branch to a Checked-out Version

A sample element, util2.c, has the following version tree (see Figure 7-7.)

Figure 7-7. Sample Version Tree for util2.c


To merge from the version /main/rel2_bugfix/LATEST to the checked-out version:

  1. From a file browser, select the checked-out element (util2.c) and choose the menu item Versions -> Merge -> From ...branch/LATEST -> view...

  2. A branch type browser prompts for a branch; select rel2_bugfix and press Ok.

  3. At this point, a prompt asks whether to do a fully automated merge, if one is possible. If you answer “ Yes” here, a terminal emulation window (see Figure 7-8) displays a character mode summary of the merge. If the merge can be completed automatically, press <Return> to exit the display window; the merge is complete.

    Figure 7-8. Automatic Merge Output


If a conflict occurs during the automatic merge (two or more contributor files differ from the base contributor file at the same location), or if you answer No to the “Automatic merge?” prompt , the merge operation takes an interactive, graphical form.

Figure 7-9 shows the graphical merge window. In this example, we have chosen not to attempt an automatic merge. Furthermore, we have already responded Yes to the first two “Accept changes?” prompts, accepting in the merged output file several modified lines from “file 3” (the checked-out version) and a one-line insertion from “file 2” (the rel2_bugfix version). Note that ClearCase calculates the base contributor file, util2.c@@/main/1, automatically (see the merge manual page for details) and includes it in the display. All other contributing files are compared against the base contributor to identify changes, insertions, and deletions.

Figure 7-9. Graphical Merge Display


Before moving on to describe the graphical merge display, note that we could perform the same merge — from /main/rel2_bugfix/latest to /main/checkedout — with any of the following procedures, and some others as well:

  • From a file browser, select the checked-out element, press the Merge button (see Figure 7-2), and select rel2_bugfix when prompted by the branch type browser.

  • From a vtree browser on element util2.c, select the menu item Version -> Merge -> From version -> branch... At the prompts, click on the “from” version and press Ok, then click on the “to” version and click Ok.

  • From a file browser, select the checked-out element, and choose the menu item Versions -> Find merge -> Selected items -> From ...branch/LATEST -> view... Select /main/rel2_bugfix from the branch type browser. Answer “Yes” to the prompt. Alternatively, answer “No” to the prompt in Figure 7-10.

    Figure 7-10. Reply Prompt “No”


Answer Yes to the prompt in Figure 7-11 (after findmerge has written merge commands to a log file/command script)

Figure 7-11. Reply Prompt “Yes”


Or, answer No to both prompts and run the .log script later.

  • From the command line:

    % cleartool xmerge -to util2.c \
     util2.c@@/main/rel2_bugfix/LATEST
    

  • From the command line:

    % cd src; cleartool findmerge . -fversion\
    /main/rel2_bugfix/LATEST -merge -xmerge 
    

The Graphical Merge Display Window

The graphical merge display shares many features with the file comparison display: difference panes, text line annotations, color usage, Next/ Prev Diff buttons, and so on. Following are the significant additions.

Merged Output Pane (Editable)

Displays the merge output as it is being built. You can edit the merged text directly (using primitive editing keystrokes) or press the Edit button to invoke a text editor. The merged output can include the following annotations:

File # 

Identifies the file that contributed the line (no annotations for lines from the base contributor file).

Edtblk 

Marks a block of text modified in a text editor with the Edit button (described below).

Edited  

Marks each line that has been manually edited in the merged output pane itself.

Calculated Base Contributor File

Unless you invoke xcleardiff directly and without a -base argument, a base contributor file is calculated automatically and displayed on the left of the screen, or on the top with vertical stacking in effect. The base contributor file is the common ancestor for all versions of the element being merged. See merge for a discussion of how ClearCase calculates the base contributor for various types of merge operations.


Note: You might do this if attempting to merge unrelated files, or files that are not elements.


Merge-Related Menu Options

File -> Restart — Cancel and restart the entire merge operation.

Options -> Query on Conflicts — The default merge automation mode. If a difference section (insertion, deletion, or change) has exactly one contributor that differs from the base file, the change is accepted automatically and applied to the merged output. You are prompted to intervene manually only when the same text section in two or more contributors differs from the corresponding section in the base file.

Options -> Query on All — Turns off automatic change acceptance, and prompts you to take action on every change from every contributor.

Options -> Pause after Auto Decisions — After each automatic merge decision (see Query on Conflicts), xcleardiff pauses and prompts “Continue merge?”. This option has no effect in Query on All mode.

Merge Processing Buttons

Yes  

Accept the current prompt (“Accept change?”, “Save Merged output?”, and so on).

No  

Refuse the current prompt. Specifically, reject the current change, insertion, or deletion section in a contributor file; preserve the base file's version of the applicable text section.

Yes/Pause  

Accept the change/insertion/deletion, but then pause merge processing; a “Continue merge?” prompt appears.

No/Pause  

Reject the change/insertion/deletion, and then pause merge processing; a “Continue merge?” prompt appears.

Edit  

(Active whenever processing is paused) Press Edit to edit the merged output file in a text editor (the system searches, in order, the visual, editor, and wineditor environment variables).While in the text editor, the Yes button is enabled as an “escape hatch” in case the editor process hangs


Note: The Edited annotation marks every line edited manually (directly in the output pane, not with a text editor), but the Edtblk annotation is somewhat less precise; it marks each text block in which one or more changes were made with the text editor.


Current Diff  

(Bottom of display window) Any pause in automatic merge processing enables the Previous Diff, Next Diff, and Current Diff buttons. If you use Previous Diff or Next Diff to move around during a pause, Current Diff resynchronizes all difference panes with the base file and returns you to the pause point—a yellow highlighted insertion, change, or deletion that the system is waiting for you to accept or reject.

Example Revisited

Let's return to the scenario in Figure 7-9 to edit the merged output, complete the merge, and check the results.

Edit the Merged Output

With merging paused at the “Accept change?” prompt:

  1. Position the cursor above the change block from File 3.

  2. Type in a comment. For example:

    /* Merged from rel2_bugfix branch:5/1/94 */
    

  3. Use a text editor to supply a matching comment.

    Press the Edit button. When the text editor comes up, add a comment below the changed block. For example:

    /* End merged section */

  4. Quit the editor and answer Yes to the prompt “Apply changes from editing session?”. The prompt returns to its state before you began editing:
    “Accept change?”

  5. Compare the new Edited and Edtblk annotations on the merged output.

Complete the Merge

  1. Answer Yes to the remaining prompts.

Check the Results of the Merge

  1. Finally, let's check the merge results for consistency by comparing the new util2.c@@/main/checkedout — which was overwritten with the merged output — against util2.c.contrib, an automatically saved copy of the original checked-out version.

    % cleartool xdiff util2.c.contrib util2.c
    

    Figure 7-12 shows the comparison.

  2. Checkin the merged file.

    % cleartool checkin -c "merged from rel2_bugfix" util2.c
    

    Figure 7-12. Verifying Merged Output