Using twmerge

28

Starting twmerge from the command line enables you to:

• Determine which files (if any) are loaded into twmerge at startup
• Specify the name of the merged output file at startup
• Specify whether or not twmerge should consider leading white space (tabs and spaces) when identifying differences
• Specify whether the merged output file is writable or read-only
• Load lists of files from specified directories
• Specify input file display names for the left and right text panes in the Merging window (Useful when merging directories of files from a list.)

When you load the two files to be merged, you can also specify a third file from which the two files were created for comparison. When you have specified this ancestor file, Merging marks lines in the descendants that are different from the ancestor and produces a merged file based on all three files

The merged version contains two types of lines:

• Lines common to both input files
• Resolved differences

Type twmerge.

The directory you start twmerge from becomes the working directory for opening and saving files.

Loading Two Files at Startup

To merge two files named file_1 and file_2, type:

demo% twmerge file_1 file_2 &

The first file, file_1, opens in the left text pane; file_2 opens in the right pane.

Loading Three Files at Startup

demo% twmerge -a ancestor_file file_1 file_2 &

The ancestor file is not shown, but differences between the ancestor file and the two descendants are marked, with the output file being based on the ancestor file.

Loading Files from a List File

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 want to merge the changes to both sets of files, and place the new merged versions in a directory named /new_src.

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

file_1 file_2 file_3

Name the file sourcelist and place it in the directory where you plan to start twmerge. Change to that directory and start twmerge by typing:

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

This command loads /usr_1/file_1 into the left text pane, /usr_2/file_1 into the right text pane, and sets the common ancestor as /src/file_1.

Current, Next, and Previous Difference

Resolved and Remaining Difference

If the Auto Merge feature is on, Merging resolves differences automatically.

Moving Between Differences

Resolving Differences

To accept a difference:

Click the Accept button, or Click the Accept & Next button to accept the difference and move to the next difference.

Comparing Three Input Files

• If a line is identical in all three files, there is no glyph.

• If a line was added to one or both of the descendants, then a plus sign (+) shows where the line was added, and the line is highlighted.

• If a line is present in the ancestor but was removed from one or both of the descendants, then a minus sign (-) shows where the line was removed, and the line is highlighted and in strikethrough font.

• If a line is in the ancestor but has been edited in one or both of the descendants, then a vertical bar (|) shows where the line was changed, and the characters that differ are highlighted.

• If a line has not changed in all three files, it is placed in the output file.

• If a line has changed in one of the descendants, the changed line is placed in the output file. Changes could be the addition or removal of an entire line, or an edit to a line.

• If identical changes have been made to a line in both descendants, the changed line is placed in the output file.

• If a line has been edited in both descendant files so that it is different in all three files, no line is placed in the output file. You must decide how to resolve the difference--either by choosing a line from a descendant, or by editing the merged file by hand.

You can disable Auto Merge by choosing Options Auto Merge. When automatic merging is disabled, the output file contains only the lines that are identical in all three files and relies on you to resolve the differences.

If you do not specify an ancestor file, Merging has no reference with which to compare a difference between the two input files. Consequently, Merging cannot determine which line in a difference is likely to represent the desired change. The result of an auto merge with no ancestor is the same as disabling automatic merging: Merging constructs a merged file using only lines that are identical in both input files and relies on you to resolve differences.

Save the output file by clicking on the Save button or choosing File Save. The name of the output file is the name you specify in the Output File field.

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, as shown in the following figure.

Usage

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

Ignores leading blanks and tabs when comparing lines.

Starts in read-only mode. Only the input file text panes are displayed, and the output text pane is absent.

Specifies a common ancestor file of the two files to be merged. The output file is based on this ancestor file and the changes to it made in the descendants.

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

Sets the file name displayed for the left pane. Use when a list of files is being loaded with the -l option, and you want to display a reference name in the twmerge window.

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.

Sets the file name displayed for the right file pane.

Specifies a file that contains a list of individual file names. Use when merging entire project directories.

twmerge 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: twmerge looks 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 start twmerge with the -l option, the Load item in the File menu changes to Load Next From List. To load successive files named in listfile, choose this menu item.

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

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

---

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, twmerge uses the file name to find a file with the same local name in each directory.

---

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.