Sun WorkShop TeamWare: User's Guide: 15 - Starting and Loading Merging

# Starting and Loading Merging | # 15 |

This chapter explains how to start Merging, load it with files, and save the output file. The chapter is organized into the following sections:

Changing Names | page 182
Starting Merging from Sun WorkShop | page 182
Loading Files from the Merging Window | page 182
Starting Merging from the Command Line | page 183
Saving the Output File | page 188

You can start Merging from Sun Workshop, or the Sun Workshop TeamWare GUI, or from a shell command line. Each method has its advantages. The command line provides flexible access to all Merging options such as loading files at startup time. However, the GUI provides the following additional capabilities:

- An easy-to-use visual interface for starting all tools

- The ability to set properties, such as a default working directory, for all tools

- A properties sheet specific to each tool that lets you specify command-line options and save the command line for use in a later session

You can also start Merging from Versioning and the Sun Workshop Resolving tool.

## Changing Names

The current release of TeamWare uses new command names, so Table 15-1 summarizes the correspondences for you. Note that the old commands still work, however this manual uses the new commands and GUI names

#### Table 15-1 Correspondences Between New and Old TeamWare Commands

Old Command | New Command | Old Tool Name | New GUI Name
codemgrtool | twconfig, teamware | CodeManager | Configuring
vertool | twversion | VersionTool | Versioning
filemerge | twmerge | FileMerge | Merging
maketool | twbuild | MakeTool | Building
freezepttool | twfreeze | FreezePoint | Freezepointing

## Starting Merging from Sun WorkShop

To start Merging from Sun WorkShop:

| Select the Merging icon in the Sun WorkShop window and click on it.

When Merging starts successfully, the Merging window opens.

## Starting Merging from Sun WorkShop TeamWare

To start Merging from Sun WorkShop TeamWare:

| Pull down the TeamWare menu from the Sun WorkShop TeamWare Configuring window and select Merging.

When Merging starts successfully, the Merging window opens.

## Loading Files from the Merging Window

To load files in Merging:

| Select Open from the File menu, or from the Open button.

The resulting pop-up window provides text fields in which to enter file names. As an example, from the directory`/usr/src, matriarch` is entered as the ancestor file, `file_1` as the left file, and `file_2` as the right file.

Working Directory-- This text field shows the current working directory whenever you start Merging from the Manager 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--The file you specify in this text field appears in the left text pane, also considered the "child" pane.

Right File--The file you specify in this text field appears in the right text pane, also considered the "parent" pane.

Ancestor File--If you enter the name of an ancestor file, Merging will compare it to the files to be merged and identify lines in those files that differ from the ancestor. The automerged file will be based on the ancestor file, but the ancestor file itself is not displayed in any Merging window. If you do not enter 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--The merged output file takes the name you specify in this text field. Merging uses the name `filemerge.out` unless you specify a different name, and stores the file in the current working directory.

Open Button--Click on the Open button to load the files you have specified in the text fields.

In a loaded Merging window the names of the left file, right file, and output file are displayed above each text pane. The name of the ancestor file (for a three-way diff only) is displayed in the window header. The "..." buttons to the right of each text field bring up a file chooser.

## Starting Merging from the Command Line

Starting Merging from the command line enables you to:

- Determine which files (if any) are loaded into Merging at startup
- Specify the name of the merged output file at startup
- Specify whether or not Merging should consider leading white space (tabs and spaces) when it identifies differences
- Specify whether Merging should produce a writable merged output file or function in read-only mode
- Load lists of files from specified directories
- Specify input file display names, which are displayed over the left and right text panes in the Merging base window (This feature is especially useful when you merge entire directories of files from a list.)

### Basic Startup Command

To start Merging from the command line without loading any input files (assuming that the Merging executable is in your search path):

| Type the following command at a command-line prompt:
    demo% twmerge &

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

### Command-Line Synopsis

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]

#### Options Defined

`-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.

> 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.

##### 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.

### Loading Two Files at Startup

To load two files at the time you start Merging, 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% twmerge file_1 file_2 &

The first file listed appears in the left text pane; the second file appears in the right pane.

### 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 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 -1 sourcelist /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`.

## Saving the Output File

Save the output file by clicking on the Save button or choosing Save from the File menu. The name of the output file is the name you specify in the Output File test field of the Load pop-up window.

The Load item on the File menu changes depending on whether or not you are loading files from a list; however, Save and Save As are available in either case.

To change the name of the output file while saving, choose Save As and fill in the new file and directory names in the resulting pop-up window. Saving an Output File Under Another Name