For a discussion of the actual file comparison and merge algorithms, see the diff and merge manual pages.
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.
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:
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:
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:
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))
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.
Open the desired directory in a file browser as shown in Figure 7-3 and select the element, util.c for example.
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.
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.
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.
By default (that is, unless line numbering is enabled), the following annotations can appear in the annotation panes:
Line occurs in this file, but not in base contributor file. (Insertions default to green on a color display monitor.)
Line occurs in base contributor file, but not in this file. (Deletions default to red on a color display monitor.)
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.
|Show Line Numbers|
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.
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:
Select util.c from a file browser.
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.
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
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.
Select the directory icon from a file browser.
Choose Versions -> Diff -> Other vs. other...
In the prompting vtree, supply the “older” version and press Ok. Then supply the “newer” version and press Ok.
The equivalent command line is:
% cd /vobs2/rell4/src; cleartool xdiff .@@/main/1 .@@/main/2
A sample element, util2.c, has the following version tree (see Figure 7-7.)
To merge from the version /main/rel2_bugfix/LATEST to the checked-out version:
From a file browser, select the checked-out element (util2.c) and choose the menu item Versions -> Merge -> From ...branch/LATEST -> view...
A branch type browser prompts for a branch; select rel2_bugfix and press Ok.
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.
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.
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.
Answer Yes to the prompt in Figure 7-11 (after findmerge has written merge commands to a log file/command script)
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 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.
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:
Identifies the file that contributed the line (no annotations for lines from the base contributor file).
Marks a block of text modified in a text editor with the Edit button (described below).
Marks each line that has been manually edited in the merged output pane itself.
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.|
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.
Accept the current prompt (“Accept change?”, “Save Merged output?”, and so on).
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.
Accept the change/insertion/deletion, but then pause merge processing; a “Continue merge?” prompt appears.
Reject the change/insertion/deletion, and then pause merge processing; a “Continue merge?” prompt appears.
(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
(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.
Let's return to the scenario in Figure 7-9 to edit the merged output, complete the merge, and check the results.
With merging paused at the “Accept change?” prompt:
Position the cursor above the change block from File 3.
Type in a comment. For example:
/* Merged from rel2_bugfix branch:5/1/94 */
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 */
Quit the editor and answer
Yes to the prompt “Apply changes from editing session?”. The prompt returns to its state before you began editing:
Compare the new Edited and Edtblk annotations on the merged output.
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.
Checkin the merged file.
% cleartool checkin -c "merged from rel2_bugfix" util2.c