Previous Next Contents Index Doc Set Home

Using twmerge


Merging lets you compare two text files, merge two files into a single new file, and compare two edited versions of a file against the original to create a new file which contains all new edits.

Starting twmerge from the command line enables you to:

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

Understanding Merging

page 354

Starting twmerge

page 354

Working with Differences

page 356

Understanding Glyphs

page 357

Merging Automatically

page 357

Saving the Output File

page 358

Command Reference

page 358

Understanding Merging

Merging loads and displays two text files for side-by-side comparison, each in a read-only text pane. Any differences between the two files are marked, and a merged version of the two files which you can edit to produce a final merged version.

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:

Starting twmerge

To start twmerge without loading any input files:

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

Loading Two Files at Startup

To load two files when starting twmerge, change to the directory in which the files are stored and type the file names on the command line.

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

To merge two files and compare them to a common ancestor, change to the directory in which the files are stored and type:

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

You can sequentially load files from a list of file names.

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:


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.

Working with Differences

Merging operates on differences between files. When Merging discovers a line that differs between the two files to be merged (or between either of the two files and an ancestor), it marks the lines in the two files with glyphs corresponding to how the lines differ. Together, these marked lines are called a difference. As you move through the files from one difference to the next, the lines that differ and their glyphs are highlighted.

Current, Next, and Previous Difference

The highlighted difference is called the current difference. The differences immediately before and immediately after are called the previous difference and the next difference.

Resolved and Remaining Difference

A difference is resolved if the changes to a line are accepted. A remaining difference is one that has not yet been resolved.

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

Moving Between Differences

You can move between differences using the buttons above the two panes, or the Navigate menu. Use the Previous and Next buttons to scroll through the differences without accepting them.

Resolving Differences

To resolve a difference, you accept the change in either the left or right pane.

To accept a difference:

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

Understanding Glyphs

Glyphs help you understand the differences between files. There are three types of glyph:

Glyph type

Plus sign

New line

Minus sign

Deleted line

Vertical bar

Change in line

No glyph

No changes in line

Comparing Three Input Files

When an common ancestor file is designates, glyphs next to the lines in each file indicate when they differ from the corresponding lines in the ancestor:

When differences are resolved, the glyphs change to an outline font.

Merging Automatically

Merging can resolve differences automatically, based on the following rules:

When Merging automatically resolves a difference, it changes the glyphs to outline font. Merging lets you examine automatically resolved differences to be sure that it has made the correct choices.

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.

Saving the Output File

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.

Command Reference

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



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.

-a ancestor

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.

-f1 name1

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.

-f2 name2

Sets the file name displayed for the right file pane.

-l listfile

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.

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

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.
outfile--Specifies the name of the merged output file. If you do not specify an outfile, the output file is given the default name twmerge.out. If you want to specify a different name when you save the file, use File Save As.

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.

Previous Next Contents Index Doc Set Home