Sun WorkShop TeamWare 2.1 User's Guide

Starting Merging

You can start Merging from a shell command line, from the Sun Workshop main window, or from another Sun Workshop TeamWare tool.

Starting Merging from the Command Line

To start Merging from the command line without loading any input files (assuming that the Merging executable is in your search path), at a shell command prompt, type twmerge followed by the ampersand symbol (&):

demo% twmerge &

The twmerge command starts Merging (in the background) without loading any files.

The complete twmerge command is summarized below, with command options enclosed in square brackets.

twmerge [-b] [-r] [-a ancestor] [-f1 name1] [-f2 name2] [-l listfile] [ leftfile rightfile [outfile] ] [-V]

-b
Causes Merging to ignore leading blanks and tabs when comparing lines.

-r

Starts Merging in read-only mode. When you specify this option, only the input file text panes are displayed, and the output text pane is absent.

-a ancestor

Specifies an existing ancestor file of the two files to be merged (called descendants of the ancestor file). The merged file is based on this ancestor file and the changes to it that have been made in the descendants.

When used with the -l listfile option, ancestor is a directory of files, which you can load in succession from the File menu.

-f1 name1

Sets the file name displayed for the first (left) file. This option is useful when a list of files is being loaded (with the -l option), and you want to display a name for reference only in the Merging window.

For example, if you are loading files from two directories that correspond to two different revisions of a product, you could use the -f1 option to display the name Rev1 above the left pane and the -f2 option to display the name Rev2 above the right pane.

-f2 name2

Sets the file name displayed for the second (right) file.

-l listfile

Specifies a file that contains a list of individual file names. This option is useful for merging entire project directories.

Merging uses the names in listfile to successively load files from directories you name with the leftfile and rightfile arguments, placing the output files in the directory you name with the outfile argument. The names in listfile must match file names in the leftfile and rightfile directories. When used with the -a ancestor option, the ancestor argument must be a directory: Merging will look in the ancestor directory for files that have the same names as those in listfile and use those with matching names as ancestor files for each merge.

If you specify the character "-" for listfile, Merging reads the list of files from standard input.

leftfile

The name of the left file to be loaded for comparison. When used with the -l listfile option, leftfile is a directory of files, which you can load in succession from the File menu.

rightfile

The name of the right file to be loaded for comparison. When used with the -l listfile option, rightfile is a directory of files, which you can load in succession from the File menu.

outfile

Specifies the name of the merged output file. If you do not specify an outfile, the output file is given the default name filemerge.out. If you want to specify a different name when you save the file, use Save As from the File menu.

When used with the -l listfile option, outfile names the directory to be used when each merged output file is saved. Individual file names in the outfile directory are the same as the names listed in listfile.

-V

Does not start up Merging, but displays the version number of the application.

Note -

If you use the -l listfile option, then all three input file names (ancestor, leftfile, and rightfile) must be directories. If you do not use the -l listfile option, then any two input file names can be directories, but one of the three must be a simple file name. In this case, Merging uses the file name to find a file with the same local name in each directory.

Loading Two Files at Startup

To load two files at the time you start Merging from the command line, change to the directory in which the files are stored and specify the file names on the command line. To merge two files named file_1 and file_2, use the following command:

demo% twmergefile_1 file_2 &

The first file listed appears in the left text pane; the second file appears in the right pane (see Figure 4-1).

Loading Three Files at Startup

To merge the same two files and at the same time compare them to a common ancestor named ancestor_file, change to the directory in which the files are stored and use the following command:

demo% twmerge -a ancestor_file file_1 file_2&

The ancestor file is not displayed, but differences between the ancestor file and the two descendants are marked, and the merged output file is based on the ancestor file.

Loading Files from a List File

You can sequentially load files into Merging from a list of file names. For example, suppose ancestor versions of a project's source files are stored in a directory named /src. You have been editing the files file_1, file_2, and file_3 in your directory /usr_1, and another developer has been simultaneously editing the same files in the directory /usr_2. You have been given the responsibility of merging the changes to both sets of files, and you want to place the merged versions in a directory named /new_src.

To merge the /src, /usr_1, and /usr_2 directories, you first create a list file that contains only the names of the three files to be merged with each name on a separate line, as follows:

file_1
file_2
file_3

Name the file sourcelist and place it in the working directory where you plan to start Merging. Change to that directory (with the cd(1) command) and start Merging with the following command:

demo% twmerge -a /src -1sourcelist /usr_1 /usr_2 /new_src &

This command causes Merging to load /usr_1/file_1 into the left text pane, /usr_2/file_1 into the right text pane, and compare both files to the common ancestor /src/file_1. After you have resolved the differences between the two files, choose Save from the File menu to automatically save the output file as /new_src/file_1.

Starting Merging From Sun WorkShop or From Another TeamWare Tool

You can start Merging from tool bar or the Tools menu in the Sun WorkShop main window, or from the TeamWare menu in another TeamWare tool:

To start Merging from the Sun WorkShop main window, click the Merging icon on the tool bar.

To start Merging from Sun WorkShop TeamWare, select TeamWare > Merging in the main window of Configuring, Versioning, or Freezepointing.

Loading Files from the Merging Window

To load files in Merging, choose File > Open or click the Open button. The Open Files dialog box (see Figure 13-1) is displayed.

Figure 13-1 Open Files Dialog Box

Directory text box	Shows the current working directory whenever you start Merging from Sun WorkShop or from the command line with no arguments. You can edit this field. Merging interprets the file names you specify in the window as relative to the current working directory. Therefore, you can use such constructs as subdir/filename to specify a file in a subdirectory and ../filename to specify a file in a parent directory. Any file name you specify that begins with a "`/`" character is interpreted as an absolute path name, not as relative to the current working directory
Left File text box	Lets you specify the file to appear in the left text pane, also considered the child pane.
Right File text box	Lets you specify the file to appear in the right text pane, also considered the parent pane.
Ancestor File text box	Lets you specify the name of an ancestor file. If you type a file name in this text box, Merging compares the file to the files to be merged and identifies lines in those files that differ from the ancestor. The automerged file is based on the ancestor file, but the ancestor file itself is not displayed in any Merging window. If you do not type an ancestor file name, Merging compares only the left and right files and derives the output file from them. Automerging is not possible without an ancestor file.
Output File text box	Lets you specify the name for the merged output file. Merging uses the name `filemerge.out` unless you specify a different name, and stores the file in the current working directory.
Open button	Loads the files you have specified in the text boxes.

In a loaded Merging window the names of the left file, right file, and output file are displayed above the appropriate text panes. The name of the ancestor file (for a three-way diff only) is displayed in the window header.

`-b`	Causes Merging to ignore leading blanks and tabs when comparing lines.
`-r`	Starts Merging in read-only mode. When you specify this option, only the input file text panes are displayed, and the output text pane is absent.
`-a` `ancestor`	Specifies an existing ancestor file of the two files to be merged (called descendants of the ancestor file). The merged file is based on this ancestor file and the changes to it that have been made in the descendants. When used with the `-l` listfile option, ancestor is a directory of files, which you can load in succession from the File menu.
`-f1` `name1`	Sets the file name displayed for the first (left) file. This option is useful when a list of files is being loaded (with the `-l` option), and you want to display a name for reference only in the Merging window. For example, if you are loading files from two directories that correspond to two different revisions of a product, you could use the `-f1` option to display the name `Rev1` above the left pane and the `-f2` option to display the name `Rev2` above the right pane.
`-f2` `name2`	Sets the file name displayed for the second (right) file.
`-l` `listfile`	Specifies a file that contains a list of individual file names. This option is useful for merging entire project directories. Merging uses the names in listfile to successively load files from directories you name with the leftfile and rightfile arguments, placing the output files in the directory you name with the outfile argument. The names in listfile must match file names in the leftfile and rightfile directories. When used with the `-a` ancestor option, the ancestor argument must be a directory: Merging will look in the ancestor directory for files that have the same names as those in listfile and use those with matching names as ancestor files for each merge. If you specify the character "`-`" for listfile, Merging reads the list of files from standard input.
`leftfile`	The name of the left file to be loaded for comparison. When used with the `-l` listfile option, leftfile is a directory of files, which you can load in succession from the File menu.
`rightfile`	The name of the right file to be loaded for comparison. When used with the `-l` listfile option, rightfile is a directory of files, which you can load in succession from the File menu.
`outfile`	Specifies the name of the merged output file. If you do not specify an outfile, the output file is given the default name `filemerge.out`. If you want to specify a different name when you save the file, use Save As from the File menu. When used with the `-l` listfile option, outfile names the directory to be used when each merged output file is saved. Individual file names in the outfile directory are the same as the names listed in listfile.
`-V`	Does not start up Merging, but displays the version number of the application.