The VisualAge TeamConnection VisualMerge Facility allows you to merge two or three selected files or directories. With the VisualMerge Facility, you have the capability to select different merge options for determining differences in a file or directory and selecting which differences go in the output file or directory.

Merge Model

The basic merge task brings developed code for a file together. The figure below shows the classic merge model, which describes the merge of three inputs into a single output. The items involved in the merge are shown in white. Items one through six represent the main stream of development for a particular part or file. Item 2 represents the base or common ancestor from which two streams proceed. At the time of the merge, the most recent version in the two streams are items 4 and 2.3. In this scenario, a user would select the base or common ancestor, item 2, as input 1. Item 4, the latest version in the main stream of development, would be used as input 2. The latest version in the branch is represented as item 2.3, or input 3. Item 5 represents the outcome of the merge.

The VisualMerge Facility follows this merge model by displaying the three inputs and the output in a main merge window. Three auxiliary windows, the Merge Navigator, Collisions, and Legend, aid in coordinating and controlling the merge.

Using VisualMerge Facility

You can use VisualMerge Facility input values from the command line, or you can specify values from the graphical user interface. A merge can be done on two or three files or directories.

Command Line Usage

Use the appropriate tool on your platform for the command prompt. The section below, Syntax Style Conventions, explains the appropriate use of the command syntax.

Syntax Style Conventions

This section explains the meaning behind each style of the command line parameters.

First letter of an argument is capitalized: You must supply these values. For example, Name or Text.
...: Parameter can be repeated on the command line. For example, -login ... Name means that you can enter more than one argument for the -login flag.
|: Separator between two possible values. For example, file1|directory1 indicates that there is an option to use either file1 or directory1.
[ ]: Optional parameters are enclosed in square brackets. For example, [-description Text] is not a required field and is optional.

Command Line Syntax

The following is a list of the command line syntax and their abbreviations. The first set of brackets encloses the abbreviation; the remainder shows the full parameter name. For example, [-re[place]] indicates that -re is the abbreviation for the replace parameter.

tcmerge <file1|directory1> <file2|directory2> [<file3|directory3>]
     [-ti[tles] <titlenames>]
     [-out <file|directory>]
     [-prime[out] <file|directory>]
     [-re[place]]
     [-ignoreco[lumns] <list of ranges to ignore>]
     [-ignoreb[lanks] <l|t|a|lt>]
     [-ignoreca[se] <file|directory>]
     [-ignoreu[nique] <file|directory>]
     [-ignoreb[lanklines]]
     [-auto[merge]]
     [-nologo]

Parameters:

file1 or directory1: The first file or directory you want to merge. If not provided, the Merge Files dialog is presented. Note that either all files or directories must be specified. A combination of filenames and directory names is not valid.
file2 or directory2: The second file or directory you want to merge. If not provided, the Merge Files dialog is presented.
[file3or directory3]: The third file or directory you want to merge. If only two files are being merged, this is not specified.
[-titles title of files]: Names describing the files or directories being merged. These names appear in the title bars of the input views while displaying the split view of the main window.
[-out <file or directory>]: The file or directory into which the merged differences will be written. The output flag is optional.
[-primeout <file or directory>]: Primes the specified input file or directory to the output window.
[-replace]: If specified, the filename with the -out flag will be replaced. If not specified, and the filename specified with the -out flag exists, a message will be displayed indicating that the -replace flag must be specified.
[-ignorecolumns <list of ranges>]: List of column ranges to ignore during the compare. Entries in this list must have the format <startColumn,endColumn> with no blanks within an entry. You can specify one column <Column> where start and end would be the same number.
[-ignoreblanks <L,T,A, or LT>]: Specifies which blanks to ignore during a compare. One of the following must be specified with this flag: L (leading), T (trailing), LT (leading trailing), or A (all blanks). When L is specified, any blanks at the beginning of a line will be ignored. T indicates that any blanks at the end of a line will be ignored. LT indicates that blanks at the beginning of the line and at the end of the line will be ignored. A indicates that all blanks on a line, leading, trailing, and embedded blanks, will be ignored.
[-ignorecase]: When this flag is specified, the case of the characters is ignored during the compare. For example, when an uppercase "C" and a lowercase "c" are compared, there will be no difference.
[-ignoreblanklines]: When this flag is specified, any blank lines are ignored during the compare.
[-ignoreunique <file or directory>]: When this flag is specified, an input file or directory is ignored during the compare.
[-automerge]: Automatically merge differences between files or directories. When conflicts are found in the merge process, the VisualMerge interface will be invoked to allow the user to resolve the conflict. If no conflicts are found, a message indicating the merge was successful is displayed.
[-nologo]: Hides the TeamConnection logo.
Default options: If you provide no inputs, the Merge Files dialog is presented. If you provide only input and output files or directories, the following defaults will be in effect:

The output file or directory is not primed with one of the input files or directories.
No columns will be ignored in difference calculation.
No blanks will be ignored in difference calculation.

The Merge Files dialog is presented when no inputs are specified at the command prompt.

Error Messages

The following are the error messages displayed on the command line of VisualMerge.

Java runtime environment needs more memory: This error can occur when trying to merge large files totalling 20k lines or more. The Java runtime environment is limited to 16 megabytes of memory as a default. To override this default, set the environment variable JAVA_OPTIONS to --mx<x>m where <x> is the maximum number of megabytes a single VisualMerge session can use.
: Example: To increase the memory limit of the Java runtime environment to 32 megabytes of memory on Windows NT, enter set JAVA_OPTIONS=-mx32m and then run VisualMerge from the same command prompt.
Unable to initialize threads: cannot find class java/lang/thread error: This error occurs when the Java runtime environment is not setup correctly. Check that the CLASSPATH environment variable is set correctly and that a 1.1 or greater version of the Java runtime environment is in the PATH environmental variable. Also confirm that the version is higher than any down level versions of the Java runtime environment listed in the CLASSPATH. Note that VisualMerge uses jre.exe on all Windows platforms, java.exe on OS/2, and java on all UNIX platforms.

Graphical User Interface: Using VisualMerge Facility Windows

Listed below are the menu bar choices found on the VisualMerge window. More help is provided in the sections labeled after the menu bar choices.

File
Edit
View
Options
Window
Help

File Menu

The File menu contains the following items:

Merge files

Select the files to merge, as well as the options for:

selecting the input file to prime the output file
selecting the columns to ignore
selecting which blanks to ignore
selecting to ignore case
automerge
assigning titles to the input files

Merge Directories

Select the directories to merge, as well as the options for:

selecting the input directory to prime the output directory
selecting the columns to ignore
selecting which blanks to ignore
selecting to ignore case
automerge
assigning a title to the directory and source drive.

Close

Closes the current merge session. It will also prompt you to save any changes.

Save Output

Saves the output file. If you have not previously saved the output, the Save As window appears.

Save Output As...

Saves the output file with a new name.

Properties

Allows you to choose editor properties such as font, tabs, colors, and layout properties, such as whether the Navigator, Legend, and Collisions (if applicable) windows come up by default, and the file location. You can also save these properties by clicking on the Save as... button on the Editor tab of the Properties notebook.

Print

Allows you to select files to print, as well as print parameters and properties.

1.File

Displays the most recent merge input file. Shows a single filename if all are the same; otherwise shows all names.

2.File

Displays the second most recent merge input file. Shows a single filename if all are the same; otherwise shows all names.

n.File

Displays the nth most recent merge input file. Shows a single filename if all are the same; otherwise shows all names.

Exit

Closes and exits VisualMerge. It will also prompt you to save any changes.

Edit Menu

Use the Edit menu to work with the composite file.

The Edit menu contains the following:

Undo: Reverses the last action.
Insert Block: Brings up a cascade menu offering choice of inserting inputs 1, 2, or 3 in the output.
Edit Current Difference: Brings up an edit window containing contents of current difference from the output window. If no difference block has been selected, the dialog box is empty.
Copy Current Difference: Copies current item in output to clipboard.
Paste to Current Difference: Pastes from clipboard into current item in output. If the number of lines in the clipboard is greater than the number of lines in the difference block, you will be prompted to copy whatever can fit in the output difference block.

View Menu

The View menu contains the following:

Composite

This changes the main window to composite view. If the current view is the composite view, this option will appear in the View menu with a check.

Split

This changes the main window to split view. If the current view is the split view, this option will appear in the View menu with a check. The split view is shown below.

Scroll Together

In the split view, this allows the windows to scroll in sync with each other when any scroll bar is selected. If the VisualMerge window is not in the split view, this option is disabled. If not checked, windows scroll indepedently.

Show Only

Provides cascade menu offering choices of all inputs, or output only.

Reset Panes

Use this option to reset panes to their original settings.

Line Numbers

Displays line numbers. Checked if on.

Next Difference

Allows you to go to the next difference.

Previous Difference

Allows you to go to the previous difference.

First Difference

Takes you to the first difference.

Last Difference

Takes you to the last difference.

Go To Difference

This brings up a dialog box which provides you with the option to go to a specific difference.

Start of Difference

Allows you to go to the top of the difference block.

End of Difference

Allows you to go to the bottom of the difference block.

Toolbar

Allows you to show the toolbar. If checked, the toolbar is already displayed.

This is the toolbar located at the top of the VisualMerge window.

Brings up the Merge Files panel.

Brings up the Merge Directories panel.

Saves the Output into a file.

Brings up the Properties notebook.

Goes to next difference.

Goes to previous difference.

Changes VisualMerge window to composite view.

Changes VisualMerge window to split view.

Status Bar

Allows you to show or hide the status bar. If checked, the status bar is already displayed.

Reference icons

These icons are located at the bottom right of the VisualMerge window. Use these buttons to bring up specific auxillary windows.

This reference icon brings up the Legend window.

This reference icon brings up the Navigator window.

This reference icon brings up the Collisions window in a directory merge.

Options Menu

The Options menu contains the following selections:

Recalculate: You can use this to recalculate the merge. You will be prompted to save these changes, since the current output will be lost by recalculating the merge. The merge options notebook then comes up.
Ignore Unique Differences: This allows you to ignore differences caused by a specific file. You can select from a cascade menu displaying None, Caused by Input 1, Caused by Input 2, and Caused by Input 3.

Window Menu

The Window menu contains the following:

Navigator

Brings up or closes the Navigator. Checked if already open. There are two Navigator views. The first view displays the placement of the differences within the output. You can select between the views by clicking on the corresponding icon and view.

This button is located on the toolbar of the Navigator window and displays the amount of the differences in the output file in grey shading.

This button is located on the toolbar of the Navigator window. This second Navigator view tracks the differences from the origin in the inputs. Each column represents an input which tracks the differences between inputs in grey shading.

Collisions

Brings up or closes the Collisions window. VisualMerge provides collisions capabilities only for directory merges. Checked if already open.

Legend

Selecting this option brings up the Legend window. Checked if already open.

Help Menu

The Help menu contains the following items:

Merge Tool Help: Displays Merge Tool Help.

Keys for VisualMerge Facility

VisualMerge Facility provides special keyboard interactions as an alternative means of using the keyboard instead of the mouse. These specific actions are defined by the following keys:

N: In the VisualMerge window, moves to next difference.
P: In the VisualMerge windows, moves to previous difference.
Ctrl+1: Selects the difference block from Input 1 and copies it to the output view.
Ctrl+2: Selects the difference block from Input 2 and copies it to the output view.
Ctrl+3: Selects the difference block from Input 3 and copies it to the output view.
Ctrl+C: Copies current output item to clipboard.
Ctrl+P: Prints the output file.
Ctrl+S: Saves the output file.
Ctrl+V: Pastes from clipboard into current output item.
Ctrl+Z: Undo. This keyboard shortcut reverses the last action.

How Do I?

Before you start working with VisualMerge Facility, you should know the path and names of the files you want to merge. The following tasks help you use VisualMerge Facility:

Merge files

Merge directories

Select a difference in the input file

Edit a line in the output file

Recalculate a file merge

Merge files

To merge files, follow these steps:

On the VisualMerge window, from the File menu, select Merge Files. Or, you can click on the Merge Files icon on the toolbar.The Merge Files dialog appears.
Type the name of the first file you wish to merge in the File 1 field, or use the Browse button to locate.
Type the name of the second file you wish to merge in the File 2 field, or use the Browse button to locate.
If you want to merge three files, type the name of the third file you wish to merge in the File 3 field, or use the Browse button to locate.
Type the name of the output file you wish to merge into in the Output field, or use the Browse button to locate.
Click on the Merge Options button if you wish to modify any attributes of the merge, such as ignoring text in certain columns, ignoring case, and ignoring blanks within lines.
Click on the OK button to begin the merge.

Merge directories

To merge directories, follow these steps:

On the VisualMerge window, from the File menu, select Merge Directories. Or, you can click on the Merge Directories icon on the toolbar. The Merge Directories dialog appears.
Type the name of the first directory you wish to merge in the Directory 1 field, or use the Browse button to locate.
Type the name of the second directory you wish to merge in the Directory 2 field, or use the Browse button to locate.
If you want to merge three directories, type the name of the third directory you wish to merge in the File 3 field, or use the Browse button to locate.
Type the name of the output directory you wish to merge into in the Output field, or use the Browse button to locate.
Click on the Merge Options button if you wish to modify any attributes of the merge, such as ignoring text in certain columns, ignoring case, and ignoring blanks within lines.
Click on the OK button to begin the merge.
The Collisions window will appear with a list of files in directory to be merged. The merge window will be updated each time a file is selected in the Collisions window.

Select a difference in the input file

There are several ways to select a difference in the input file. To select from menu choices:

Go to the Edit menu and select Insert Block. The Insert Block cascade menu appears, offering a choice of inputs to be inserted.

To select a difference within the VisualMerge window:

Select a difference by single-clicking on a line in the input. The difference is then brought over to the corresponding line in the output.

To select a difference using the keyboard shortcuts:

Select a difference from the first input file with the keys <ctrl>+1. Select a difference from the second input file with the keys <ctrl>+2. If applicable, select a difference from the third input file with the keys <ctrl>+3.

Edit a line in the output file

There are two ways to edit a line in the output file. To select from menu choices:

On the VisualMerge window, from the Edit menu, select Edit Current Difference. An Edit Current Difference dialog appears.
The line number of the current difference is displayed. Modify the text in the field.
Change the line number by typing the number of the line in the goto field or by clicking on the arrows. Once you are finished editing, click on OK.

To edit a line in the output file within the VisualMerge window:

Double-click on the current difference in the output file.

Recalculate merge

To recalculate the merge, follow these steps:

On the VisualMerge window, from the Options menu, select Recalculate. A warning window appears, prompting you to save the current output.
When you dismiss the warning, the Merge Options dialog appears. Modify any attributes of the merge, such as ignoring text in certain columns, ignoring case, ignoring blank lines, and ignoring blanks within lines.
Click on the OK button to begin the merge.