Legacy File Merge Tool

The File Merge Tool, previously called the Serena Merge Tool, enables you to compare the differences between two or more files with a common ancestor or base file, accepting or rejecting the differences between them, and combine the changes into a new file or item revision. These files can be revisions of the same item or different items in Dimensions CM, or files in your work area.

Note: When using the web client on UNIX platforms, the mgdiff tool is invoked. Use the Help option for details. UNIX users can also choose to plug in their own differencing tools, such as xxdiff. For details, read the merge_exec script in your client installation.

Overview

The merging process enables you to compare the differences between two (or more) files with a common ancestor or base file, accepting or rejecting the differences between them, and combine the changes into a new file or item revision.

The comparing process allows you compare two files side-by-side to see the additions, deletions, and changes between them. You cannot print or save the comparison file.

Note: You cannot compare or merge binary files.

The difference between comparing and merging files is:

  • You do not select a target file when you a performing a compare.

  • When you perform a compare from within the desktop or web clients you can only select two files, an ancestor and one derivative.

  • When you merge files, you must resolve all the conflicts before you can complete the merge.

The merge process consists of:

  • Selecting an ancestor file as the reference against which the derivatives will be compared.

  • Selecting one or more derivatives.

  • Selecting the file or item revision to be the target.

  • Selecting the differences which have no conflicts and inserting them into the target. If you have selected the Auto Merge option, all the differences except for conflicts will be automatically included in the target.

  • Resolving conflicts between the base and derivative files by choosing which version of each conflicting change to include in the target.

  • Saving the changes made to the target file.

If you are performing a file merge in the web client or desktop client, the selection of the ancestor, derivatives and target is made from the dialog within that client, so that when you enter the Merge tool the main window is displayed with those files already selected. You will then choose which differences to carry forward to the target file.

If you are opening the Merge tool from outside a source control application, you will either choose the ancestor, derivatives and target by specifying them in a configuration file, or by completing the Files tab of the Configuration dialog box.

Rules for identifying conflicts

The File Merge Tool identifies a line as a conflict between the derivatives based on the following rules:

  • If a line is an addition in more than one derivative, but is different between the derivatives.

  • If a line is a deletion in at least one derivative and is marked as a modification in at least one other derivative.

  • If a line is a modification in more than one derivative but is different between the derivatives.

Back to top

Merge terms and definitions

The following table provides a list of basic merge terms and definitions.

Term Definition

Ancestor or base

The common base file from which other files are derived.

Derivative or branch

A version of a file created by making changes in the ancestor file.

Target or output

The final merged file.

Addition

A line of text added to a derivative file that is not in the ancestor file.

Deletion

A line of text deleted in a derivative file that is present in the ancestor file.

Change or Modification

A line of text that was modified in one of the derivative files. The content of this line of text differs between the derivative file and the ancestor file.

Difference

A line of text added, deleted, or modified in a derivative file compared with the ancestor file.

Conflict

A line of text that was changed differently in more than one derivative file. The difference in this line of text is not the same between derivative files and the ancestor file.

Back to top

Manually complete the merge

Manually complete the merge when:

  • There are conflicting differences between the derivatives, and you need to select which versions to include in the target.

  • You have not selected the Auto Merge option, and you need to manually select which differences are included from the derivatives or ancestor.

  • You want to make other changes by editing the target file.

To select which differences to include in the target:

  • To select a difference for inclusion in the target, right-click the required line in the ancestor or derivative window. To select two adjacent differences, use Ctrl and right-click. The color of the lines will change to the selected color.

  • To clear a difference from inclusion in the target, right-click a selected line. To clear two adjacent differences, use Ctrl and right-click. The color of the lines will change to the unselected color.

  • To insert all the differences, including conflicts, for a given derivative into the target, select Edit | Select All, or press CTRL+A. All the lines in the selected derivative will change to the corresponding selected colors.

Note: Selecting all differences in one derivative does not mean you have cleared all differences in another derivative.

To edit the target file:

To copy text, select the text to be inserted into the target and click the Copy button, or use keyboard shortcut CTRL+C.

To paste text into the target, point the mouse to where you want to insert the text and click the Paste button or press Ctrl+V.

To edit text in the target, type or overtype the text in the target window.

To undo editing, select Edit | Undo, or or use keyboard shortcut CTRL+Z.

To save the target file, select File | Save Target or click Save tbsavetw.gif.

Back to top

View files in the File Merge Tool

Use the content windows to view the lines of text in the ancestor, derivatives, and target files. You can show or hide these windows and arrange them in the Merge Tool main window.

To show or hide the content windows:

  • To show or hide the Ancestor, select Windows | Display Ancestor or click the tbopnancwn.gif button.

  • To show or hide the Ancestor in the Derivative Frame window, select Windows | Display Ancestor in Frame or click the tbdisancfrm.gif button.

  • To show or hide the Consolidated View window, select Windows | Display Consolidated View, or click the tbopncvwn.gif button.

  • To show or hide the Consolidated View in the Derivative Frame window, select Windows | Display Consolidated View in Frame or click the tbdisconsfv.gif button.

  • To show or hide the Target window, select Windows | Display Target, or click the tbopntarwn.gif button.

  • To display the Global Comparison window, double-click a changed line in the ancestor or a derivative. Note that you cannot do this on an unchanged or padded line.

  • To display the Error Log window, select File | Error Log.

  • To open the Color Tips window, select View | Color Tips, click the tbopnctps30.gif button, or press CTRL+T. This window displays the current settings of colors and patterns used to identify the differences.

To change the way the windows are displayed:

  • To synchronize scrolling, select View | Sync Scrolling or click the tbactsysc30.gif button. When this option is selected, the lines in the other windows are scrolled in synchronization when you scroll one window.

  • To show or hide the line numbers, select View | Show Line Numbers or click the tbshlineno.gif button.

  • To show only differences, select View | Show Only Differences or click the tbdisdfmw30.gif button. When this option is selected, only lines that differ between one or more derivatives are displayed.

  • To set automatic resizing of windows on or off, select Windows | Auto Resize or click the tbresize.gif button.

  • To show or hide the status bar, select View | Status bar or click the tbtogstat.gif button.

To navigate the content windows:

  • To move between windows, click Next Window tbmvenxwn.gif or press F8 to go to the next window. Click Prev Window tbmveprwn.gif or press F7 to go to the previous window.

  • To move between conflicting lines, click Next Conflict next_conflict_button.gif or press F6 to go to the next conflict. Click Prev Conflict previous_conflict_button.gif or press F5 to go to the previous conflict.

  • To move between line differences, click Next Difference tbmvenxdf.gif or press F4 to go to the next line with a difference. Click Prev Difference tbmveprdf.gif or press F3 to go to the previous line with a difference.

  • To navigate using the Consolidated View, double-click a changed line to go to that line.

  • To navigate using the Ancestor Window, double click a changed line to go to that line. This only works when the target is displayed in its own window and not the Derivative Frame window.

  • To go to a line number in the current derivative or ancestor, select Edit | Go To, or press CTRL+G. Enter the required line number.

  • To search for a line containing a text string, select Edit | Find, or press CTRL+F.

Back to top