SourceGear DiffMerge

3.2 User Manual

By SourceGear LLC

Contents
SourceGear DiffMerge 3.2

SourceGear Contact Information

Installation

Windows ..............................................................................................................................3
Using the .msi: ........................................................................................................3
Using the .zip:.........................................................................................................3
Linux....................................................................................................................................3
Macintosh.............................................................................................................................4

The File Diff/Merge Windows

Opening a File Window ........................................................................................................5

Toolbar.................................................................................................................................6
Window Layout ....................................................................................................................7
Window Splitter Orientation....................................................................................8
Displaying Files..................................................................................................................10
Basic File Display .................................................................................................10
Detail Level ..........................................................................................................12
Filtering Text ........................................................................................................13
Types of Changes..................................................................................................17
Editing................................................................................................................................20
Interactive Editing.................................................................................................20
Patch Operations ...................................................................................................20
Merge to Center Panel (Auto-Merge).....................................................................21
Undo/Redo............................................................................................................21
Moving Around within Files ...............................................................................................22
Find... ...................................................................................................................22
Find Next / Find Previous......................................................................................22
Go To Line............................................................................................................23
Next and Previous Change.....................................................................................23
Next Conflict and Previous Conflict ......................................................................23

The Folder Diff Window

24

Opening a Folder Diff Window ...........................................................................................24

Folder Diff Windows Layout ..............................................................................................25
Viewing Options.................................................................................................................25
Display Detail.....................................................................................................................25

The Options Dialog

27

File Windows .....................................................................................................................28

SourceGear DiffMerge 3.2 User Manual

Contents iii

Rulesets ..............................................................................................................................30
Editing Rulesets ....................................................................................................31
Detail Level ........................................................................................................................39
Analysis Detail Level ............................................................................................39
Multi-Line Intra-Line Analysis Detail Level ..........................................................40
Intra-line Smoothing Threshold .............................................................................41
Inter-line Smoothing Threshold .............................................................................41
Line Colors.........................................................................................................................42
Intra-Line Colors ................................................................................................................43
Other Colors .......................................................................................................................44
Folder Windows .................................................................................................................45
Folder Filters ......................................................................................................................46
Folder Colors......................................................................................................................48
Messages ............................................................................................................................49
Windows Explorer Integration ............................................................................................50
External Tools ....................................................................................................................52
Add/Edit External Tool .........................................................................................53

Printing

56

Print Preview Dialog...........................................................................................................56

The Goto Page Dialog.........................................................................................................58

Command Line Arguments

59

Integration with Third-Party Software

61

Microsoft TFS ....................................................................................................................61

TortoiseSVN.......................................................................................................................61

iv Contents

Regular Expressions

63

SourceGear License Agreement

65

SourceGear DiffMerge 3.2 User Manual

SourceGear DiffMerge 3.2

Welcome to DiffMerge. DiffMerge enables you to perform three crucial tasks:

Compare two files side-by-side and see their differences. Normally this is used to compare two
different versions of a file and see how the file has changed.

Compare three files side-by-side-by-side. Normally this is used to merge the changes from two
independent (branched) versions into one file based upon a common ancestor version.

Compare two folders side-by-side. Each file in each folder is shown to be different, identical, or
without a match in the other folder.

SourceGear DiffMerge 3.2 User Manual

SourceGear DiffMerge 3.2 1

SourceGear Contact Information

Mailing Address
SourceGear LLC
115 North Neil Street, Suite 408
Champaign, Illinois, 61820, USA
Sales
Web: https://store.sourcegear.com/sgstore/
Email: [email protected]
Phone: 1-217-356-0105 x399 (weekdays 9am to 4pm Central United States time)
FAX: 1-217-356-0135.
Support
Web: http://support.sourcegear.com/
E-mail: [email protected]
Phone: 1-217-356-0105 x700 (weekdays 9am to 4pm Central United States time)
This copy of DiffMerge is licensed to you under the terms listed in the license agreement.
SourceGear is a registered trademark of SourceGear LLC.
SourceGear DiffMerge is a trademark of SourceGear LLC.
Copyright (C) 2003-2008 SourceGear LLC. All rights reserved.

2 SourceGear Contact Information

SourceGear DiffMerge 3.2 User Manual

Installation

DiffMerge works can be installed on three platforms: Windows, Linux, and Macintosh.

Windows
DiffMerge is distributed for Microsoft Windows as a standard Microsoft Installer .msi package or a .zip archive. The
filename of the file contains release and build information; for example, the packages for the 1000 build of the 3.2.0
release are named DiffMerge_3.2.0.1000.msi and DiffMerge_3.2.0.1000.zip.

Using the .msi:

To install DiffMerge using the .msi file, simply click the .msi file and follow the on-screen instructions. This will install
the application in Program Files, register a Windows Explorer shell extension, create menu items in the Start Menu, and
create a Desktop Shortcut. This is the preferred method of installing the application.
To uninstall DiffMerge either click the .msi file or use the Add/Remove Programs Control Panel.

Using the .zip:

If for some reason you cannot use the .msi file or simply prefer to use the .zip file, you may simply unzip the .zip file
somewhere on your system and execute DiffMerge.exe. You can create menu items in the Start Menu and Desktop
Shortcut if you want. You can register the Windows Explorer shell extension by running regsvr32.exe or by using the
DiffMerge Options Dialog.
To uninstall DiffMerge after using the .zip file, simply delete the folder containing DiffMerge. If you installed the
Windows Explorer shell extension, uninstall it (either using regsvr32.exe or the DiffMerge Options Dialog) before
deleting the DiffMerge folder.

Linux
DiffMerge is distributed for Ubuntu Linux as a debian .deb package. The filename of the .deb contains release, build, and
platform information; for example, the package for the 1000 build of the 3.2.0 release for Ubuntu 6.10 on Intel is named
diffmerge_3.2.0.1000-1ubuntu610_i386.deb
After downloading the most recent .deb file, you can install DiffMerge using the following command from a terminal
window:
sudo dpkg -i diffmerge_3.2.0.1000-1ubuntu610_i386.deb
This completely installs DiffMerge, including an executable in /usr/bin, a man page, and a menu item in the Ubuntu
Application|Programming menu.

SourceGear DiffMerge 3.2 User Manual

Installation 3

If you are installing on a 64-bit system, you may have to add "--force architecture" to the dpkg install
command line.
To uninstall, type the following from a terminal window:
sudo dpkg -r diffmerge

Macintosh
DiffMerge is distributed for Apple Mac OS X as a standard disk image .dmg file. It contains a Universal binary that can
run on both PPC and Intel systems. The filename of the .dmg contains release and build information; for example, the
package for the 1000 build of the 3.2.0 release is named DiffMerge.3.2.0.1000.dmg
After downloading the most recent .dmg file, click to let OS X open it. Inside you will find the DiffMerge application.
Simply drag it to your Applications folder. This application is completely self-contained; copies of the license and
manual files are included in disk image folder for your convenience. A sample shell script is also provided to make it
easier to use DiffMerge from the command line. You may want to put this folder in your PATH. You may need to edit
it to set the DiffMerge application pathname to match where you installed DiffMerge.
To uninstall, open your Applications folder and move the DiffMerge application to the trash.

4 Installation

SourceGear DiffMerge 3.2 User Manual

The File Diff/Merge Windows

There are two types of file windows File Diff Windows and File Merge Windows. They are discussed together here
because they share multiple features.
The first is a two-way view showing the differences between two files or two versions of the same file; this is called a
File Diff Window. You can use this window to see the changes side-by-side. And you can edit the file on the right,
either interactively as you would with a normal editor or by applying patches (or changes) from the version on the left.
You can use this window, for example, when looking at the revision history of a file to see the changes between two
revisions.
The second is a three-way window that shows the differences between three files; typically this is a common ancestor (in
the middle) and two branches that have independently evolved (on the left and right). This is called a File Merge
Window. You can use this window to see the changes side-by-side-by-side. You can edit the center file and merge in
changes from both branches, creating a common/unified version.

Opening a File Window

You can open a File Window by selecting File|Open Diff Window or File|Open Merge Window from the menu. You
are given a brief Select Files to Compare Dialog enabling you to type the pathnames of the files you wish to compare;
browse buttons are provided that open the standard system File Open Dialog.

Note: if the set of files selected are already open in another window, that window is raised rather than a new,
duplicate window.

SourceGear DiffMerge 3.2 User Manual

The File Diff/Merge Windows 5

Toolbar
A toolbar above the File Diff/Merge Window presents the following icons. Some appear only in the 3-Way Merge
Window.

Show All

Undo the Last Edit

Show Differences Only

Redo the Last Edit

Show Differences with Context

Apply Change from Left

Show Line Numbers

Apply Change from Right

(3-Way Merge Only)

Show Invisibles

Jump to Next Change

Split Windows Vertically

Jump to Previous Change

Split Windows Horizontally

Jump to the Next Conflict

(3-Way Merge Only)

Save File

Jump to Previous Conflict

(3-Way Merge Only)

Cut

Merge to Center
(3-Way Merge Only)

Copy

Paste

6 The File Diff/Merge Windows

SourceGear DiffMerge 3.2 User Manual

Window Layout
The File Diff/Merge Window shows two or three files side-by-side. Around these file panels are several important
features.

Field

Meaning

File Panel Labels

File panel labels show either the pathnames of the files youre comparing or labels describing the
versions of the file.

Glance Bar

The Glance Bar summarizes the differences between the files displayed on screen. The black
vertical bars indicate what portion of the files are on screen; they track the vertical scrolling of the
files.
The colored bars indicate changes in the files; the coloring and shape of the bars reflects the color
and shape of the change within the files as though seen from a birds-eye.
As the mouse moves over the Glance Bar, the line numbers of the corresponding location are
shown in the Status Bar. A star "*" is used when the line represents a Void line in a file panel.
Click the Glance Bar to scroll to that line in the file.

View Selector

The view selector enables you to select between the Reference View and Edit View.
The Reference View is a static view of the changes in the files as originally read from disk. In
this view the files are considered read-only. You may scroll around and view the differences and
you may copy things to the clipboard -- but you cannot modify the files.
This mode can be useful in various situations, such as when you want to see the changes between
two historical versions of a file.
The Edit View is an interactive editor and live difference viewer. It enables you to make changes

SourceGear DiffMerge 3.2 User Manual

The File Diff/Merge Windows 7

to the center panel in a File Merge Window and the right panel in a File Diff Window. As you
edit, your changes are highlighted, the files are re-compared in real-time, and their changes are
displayed.
The View Selector is only present when editing is permitted on the files. When not present, the
window only shows the Reference View and treats all files in the window as read-only.
Active Ruleset

The Active Ruleset Indicator shows the current Ruleset in use in this window. The Ruleset
provides rules for comparing and displaying file content (such as whitespace handling and
character encodings).

Character
Encoding

The Character Encoding Indicator shows the character encoding of the files. If all 3 have the same
encoding, it is listed once. If they are different, each is listed. "(BOM)" is listed with the encoding
when a Unicode Byte Order Mark is present.

Change Summary

The Change Summary Indicator shows a brief summary of the number of changes and conflicts
in the current View.

Window Splitter Orientation

By default, DiffMerge shows the files side-by-side with vertical splitters between them. This mode allows you to
easily see and match up the corresponding lines in the files. However, you may have to scroll horizontally to see parts of
a line.

DiffMerge also lets you view the files one above another with horizontal splitters between them. In this mode, it may
be a little difficult to see the line correspondence, but you should be able to see the entire line in each file. In this mode,
the order of the files is the same: editing takes place in the bottom/right file in a File Diff Window and the center file in a
File Merge Window.

8 The File Diff/Merge Windows

SourceGear DiffMerge 3.2 User Manual

SourceGear DiffMerge 3.2 User Manual

The File Diff/Merge Windows 9

Displaying Files
Within a file panel, file content is drawn in a variety of ways to show equal text, non-equal text, edited text, invisible
characters, omitted lines, and other information.

Basic File Display

The following figure and its accompanying chart show some of the most basic features of file panels shown in
DiffMerge windows.

10 The File Diff/Merge Windows

SourceGear DiffMerge 3.2 User Manual

Field

Meaning

Identical Text

Identical text is show in plain black and white.

Normal Context Menus are available that include traditional commands for editing text.

Changed Text

Changed text is shown in color. The specific colors used depend upon the Type of Change
and the Detail Level setting.
Special change-related Context Menus are available that include additional commands for
working with changes.

SourceGear DiffMerge 3.2 User Manual

The File Diff/Merge Windows 11

Highlighted Change

Highlighted changes are surrounded by a dotted line. When a change is highlighted, it may
be acted upon by the Apply Change from the Left and Apply Change from the Right toolbar
buttons.

Voids

Voids are drawn when a change has fewer lines than the corresponding section in another
panel.

Edited Text

Edits are shown in bold and underlined.

Edited Line Indicator

Edited lines have an "e" drawn in the left margin when View|Show Line Numbers is on.

Manual Alignment
Markers

Manual Alignment Markers enable you to force the alignment within the difference
analysis. They are drawn as a pair of dashed lines between two lines of text.

Invisible Characters

Tabs, spaces, carriage returns, line feeds are drawn using special characters when View|Show
Invisibles is on.

Gaps

Gaps are drawn as a horizontal line between rows of text to indicate that chunks of text have
been omitted from the display. These are used, for example, when the Display Mode is set to
Changes Only.

Detail Level
DiffMerge has two Detail Levels: Lines Only and Lines and Characters.

Lines Only: DiffMerge only performs difference analysis line-by-line. Changes are indicated based upon
equality of the entire line (subject to the Overall Line Matching settings in the active Ruleset). Lines are
colored without intra-line highlighting.

Lines and Characters: DiffMerge performs line-by-line difference analysis and then within each change
performs intra-line difference analysis. Lines are colored using the overall line status color and then intra-line
highlights are added.

12 The File Diff/Merge Windows

SourceGear DiffMerge 3.2 User Manual

Filtering Text
DiffMerge can show you all the text, the entire content of your files, or it can hide things that are not currently of
interest.

The Display Mode

There are three primary ways to display files. Each is accessible from the View menu as well as through toolbar icons:

Show All: This mode shows the complete text of the files.

Show Differences Only: This mode only shows the changes in the files. Gaps are drawn where content is
hidden.

Show Differences with Context: This mode shows changes with up to three lines of context around each.
Gaps are drawn where content is hidden.

The display modes Show Difference Only and Show Differences with Context are only available in Reference View.

Hide Omitted Lines

This option hides lines that were omitted from the difference analysis. When omitted lines are drawn, they are drawn in a
special gray color; when not drawn, a horizontal line is drawn to indicate a Gap.

SourceGear DiffMerge 3.2 User Manual

The File Diff/Merge Windows 13

These figures show a pair of C++ source files using a modified version of the C/C++/C# Ruleset that omits lines
beginning with "//" from the analysis.

Note how these lines are drawn in gray in the first figure; this indicates that they were excluded from the analysis. In the
second figure a Gap is drawn in their place.

14 The File Diff/Merge Windows

SourceGear DiffMerge 3.2 User Manual

You must be in Reference View and have the Display Mode set to Show All to use this feature.

Hide Unimportant Differences

DiffMerge classifies all changes as Important or Unimportant based upon information in the current Ruleset. The Hide
Unimportant Differences option causes DiffMerge to de-emphasize the coloring and display unimportant changes. When
the Display Mode is set to Show All, unimportant changes are displayed in subdued colors in the file panels and not
shown in the Glance Window. When the Display Mode is set to Show Differences Only or Show Differences with
Context, unimportant changes may be excluded.
These figures show a pair C++ source files using the C/C++/C# Ruleset with Display Mode set to changes only.

SourceGear DiffMerge 3.2 User Manual

The File Diff/Merge Windows 15

The first figure shows DiffMerge with Display Mode turned on; the second figure shows DiffMerge with Display Mode
turned off.

You must have the Detail Level set to Lines-and-Characters to select this feature (View|Hide Important Differences).

16 The File Diff/Merge Windows

SourceGear DiffMerge 3.2 User Manual

Types of Changes
Changes and Conflicts are highlighted using various text colors, depending on the type of change and the current Detail
Level.

File Diff Window Changes

There are three types of changes in a File Diff Window:
Additions

Lines added to the file on the right that were not present in the original.

Deletions

Lines deleted from the file on the right that were originally present in the file on the left.

Changes

Lines that were changed between the two versions. This can be either changes to an existing line or a deletion and
addition at the same point in the file -- either way, it looks like a change.

The coloring is simple. The same color is used to highlight all three types of changes. When the Detail Level is set to
Lines Only, you see something like the following:

SourceGear DiffMerge 3.2 User Manual

The File Diff/Merge Windows 17

File Merge Window Changes

There are nine types of Changes and four types of Conflicts that can occur when three files are compared.

Changes occur on lines where one of the three files is different from the other two. For example, an addition to
one of the branches. The Matching Lines in the two files are colored using the Matching Color and the NonMatching Line in the other file is colored using the Non-Matching Color.

Conflicts occur on lines where all three are different.

When the Detail Level is set to Lines Only, you see a screen similar to the following:

Conflict Aggregation
As a precaution, adjacent or overlapping changes are aggregated into a single change. Usually this produces a conflict
(depending on the individual types of changes in the grouping). When youre merging multiple files, these usually
require your attention because DiffMerge cannot automatically determine what to do with them.
For example, in the figure below, "Line 1" was added to both branches (in the left and right panels) and "Line 2" was
deleted from the right panel. So what should the merge result look like?

18 The File Diff/Merge Windows

SourceGear DiffMerge 3.2 User Manual

To access an individual line change within a block of changes, hold down the Control key while using the left or right
mouse buttons to select the desired line.

SourceGear DiffMerge 3.2 User Manual

The File Diff/Merge Windows 19

Editing
DiffMerge enables two types of editing: Interactive Editing and Patch Operations.

Interactive Editing
Interactive Editing refers to the normal editing operations found in most text editors and includes inserting/deleting text
with the keyboard and mouse and the standard cut/copy/paste clipboard operations.
Editing is only permitted in Edit View in the Editable Panel. In File Diff Windows the Editable Panel is the right
panel; in File Merge Windows the Editable Panel is the center panel.

Patch Operations
Patch Operations are a convenience mechanism for applying changes to the Editable Panel in the Edit View from one
of the other file panels. For example, Apply Change from Left copies the text from the left panel to the editable panel;
depending on the type of change, this can either be an Insert, a Replace or a Delete.
To perform a Patch Operation, highlight a Change or Conflict and raise a context menu over it with the right mouse
button. This lists the appropriate Patch Operations for the particular type of change.
Most of the time, the first item in the context menu will be labeled with "(default)" -- this is the Default Action. To
apply the default action you can shift-right-click on the change or select one of the Apply Change from Left or Right
toolbar buttons to automatically apply the individual change without raising the context menu. For conflicts, there isn't a
Default Action.

Apply Change from Left

Apply Change from Right

Tip: The exact wording of the menu item depends upon which window the mouse is clicked in -- contrast "Insert This"
when clicking on the left panel vs. "Insert From Left" when clicking in the center panel.
All Patch Operations are variations of one of the following verbs and refer to the content of the currently highlighted
change or conflict within each file panel.
Insert
Replace

This option inserts content from the source panel into the Void in the edit panel.
This option deletes the content in the editable panel and inserts the content from the source panel.

20 The File Diff/Merge Windows

SourceGear DiffMerge 3.2 User Manual

Delete
Prepend
Append

This option deletes the content in the editable panel.

This option inserts the source content before the existing content in the editable panel.
This option appends the source content after the existing content in the editable panel.

Merge to Center Panel (Auto-Merge)

Auto-Merge automatically applies the Default Action for all of the non-conflict changes in a File Merge Window. The
goal of Auto-Merge is to automatically take care of the easy changes so that you can focus on the conflicts.
For each automatic change made in the right and left panels, the default Patch Operation is applied for that type of
change. This is done as a batch (in 1 transaction) and may be undone using Undo.

To start Auto-Merge, select Edit|Merge to Center Panel, or click the toolbar button
After Auto-Merge completes, The Auto-Merge Results dialog displays a report on what changes were made, from
where they came, and finally a notification about what conflicts could not be merged.

It is strongly recommended that if you wish to use Auto-Merge you use it BEFORE making any other edits in the
window. This prevents Auto-Merge from possibly reverting some of your edits. Also, after Auto-Merge has been applied
to a window, it is disabled. This is to prevent Auto-Merge from being used twice and possibly reverting some edits made
by the first Auto-Merge.

Undo/Redo
DiffMerge features an unlimited Undo/Redo so that it is possible to undo changes all the way back to the initial state.

SourceGear DiffMerge 3.2 User Manual

The File Diff/Merge Windows 21

Moving Around within Files

DiffMerge offers a number of ways to find key text within a File Diff and File Merge Windows.

Find...
The Find Dialog is accessed from Edit|Find. It can be used to search forward or backward for text within the files.
Check boxes and radio buttons enable you to ignore case, search using Regular expressions, and choose which file panel
you wish to search from.

When searching with Regular Expressions, backward searching is disabled.

Find Next / Find Previous

Edit|Find Next and Edit|Find Previous repeat the last search performed by the Find Dialog.

22 The File Diff/Merge Windows

SourceGear DiffMerge 3.2 User Manual

Go To Line...
The Go To Line Dialog is accessed from Edit|Go To Line. It enables you to jump to a specific line in the file.

Next and Previous Change

The Next Change and Previous Change commands enable you to quickly jump between changes in the files.

To jump to the next change in the file, click

or select Edit|Next Change.

To jump to the previous change in the file, click

or select Edit|Previous Change.

Next Conflict and Previous Conflict

The Next Conflict and Previous Conflict command are available only in the File Merge windows and enable you to
skip to places where the right panel and left panel have both been changed from the original version, but not in the same
way.

To jump to the next conflict, click

To jump to the previous conflict, click

SourceGear DiffMerge 3.2 User Manual

or select Edit|Next Conflict.

or select Edit|Previous Conflict.

The File Diff/Merge Windows 23

The Folder Diff Window

The Folder Diff Window enables you to compare two folders and quickly see all of the differences between them. That
is, it shows you which files and folders are present in both or only present in one. It also shows you which files are equal
in both folders and which are not.
You can use this, for example, to compare two versions of a software project and quickly see an overview of the changes
between them. You can then click on individual non-equal files to open a File Diff Window and see the individual
changes within the files.
The Folder Diff Window is a recursive listing; that is, it examines all files and folders contained within the given root
folders and all sub-folders regardless of how deeply the folders are nested. Producing a listing in a large folder tree can
take a significant amount of time.

Opening a Folder Diff Window

To open a Folder Window, select File|Open Folder Diff. You are given a brief Select Folders to Compare Dialog
enabling you to type the pathnames of the folders you wish to compare; browse buttons are provided that open the
standard system Browse for Folder dialog.

Note: if the set of folders selected are already open in another window, that window is raised rather than creating a
new, duplicate window.

24 The Folder Diff Window

SourceGear DiffMerge 3.2 User Manual

Folder Diff Windows Layout

The following image shows the key features of a Folder Diff Window.

The window has two columns listing the files and folders that are present in the two folders being compared. This is a
recursive listing; all sub-folders are completely expanded. Lines are colored and an icon is attached to each line based
upon the status of the files or folders on the line. The status bar contains a summary of the number of files and folders
listed.
For files present in both folders, DiffMerge indicates which are identical and which are different.

Viewing Options
Within the Folder Diff Window you can open new File Diff Windows or Folder Diff Windows by double-clicking a
line in the list or using the View|Compare Selected Files or View|Compare Selected Folders commands.

Display Detail
The Folder Diff Window enables you see all files and sub-folders in the folders; alternatively you can have it omit
various types of items so that you can decrease clutter and concentrate on the important items more easily.

SourceGear DiffMerge 3.2 User Manual

The Folder Diff Window 25

View|Show Equal Files causes equal files to be shown or hidden.

View|Show Files without Peers causes peerless files to be shown or hidden.

View|Show Folders causes sub-folders to be shown or hidden.

Selecting (or unselecting) View|Show Errors causes file system errors to be displayed or hidden.

26 The Folder Diff Window

SourceGear DiffMerge 3.2 User Manual

The Options Dialog

The Options dialog box presents the user with a variety of options, the titles of which are listed on the left side of the
Options dialog.
Each section of the Options dialog has three elements in common - the buttons on the bottom of its screen. OK and
Cancel provide their usual functions, and Restore Defaults is ideal for turning things back to normal if you've made one
change too many and are unhappy with the result. Restore Defaults restores all of the fields ONLY ON THE CURRENT
PAGE of the dialog to factory settings. If you wish to restore defaults you altered from another page of the Options
dialog, youll have to do it from the individual page.
To access the Options dialog, select Tools|Options.

SourceGear DiffMerge 3.2 User Manual

The Options Dialog 27

File Windows
By default, File Windows is the first dialog page that opens when you first start DiffMerge and access Options. This
dialog enables you to change the default fonts for displayed files and printer files by selecting the Choose buttons.

The third portion of the dialog page enables you to click a variety of options on and off.
Field

Meaning

Check for Modified Files

When selected, DiffMerge checks to see if the files were changed by another
application while the DiffMerge window was not the front window. A message
box informs you if files were changed, offering you a chance to reload them.

Print Files Interleaved

When printing file windows, DiffMerge actually prints 2 (or 3) files

simultaneously. When this option is checked, DiffMerge prints all the page 1s
first, then all the page 2s, and so on. When this option is off, DiffMerge prints all
of the left file pages, then all of the center file pages and then all of the right file
pages.

28 The Options Dialog

SourceGear DiffMerge 3.2 User Manual

Require Final EOL

When this option is enabled, DiffMerge adds the appropriate end of line
character(s), if necessary, to the end of the final line of the file before saving.

Enable Auto Save

This option directs DiffMerge to periodically save the edited file in a special
temporary file. In the event of a program or system crash, you can recover your
work from the temporary file. Auto save does not modify the original file.
The auto-save is performed after a user-adjustable number of edits. For example,
if the edit-interval is set to 100, then the auto-save file is rewritten after every 100
changes.

Automatically Advance

If this option is checked, DiffMerge automatically advances the patch-highlight to

the next change/conflict when you press one of the "apply change from" toolbar
buttons. This enables you to rapidly apply changes without having to advance
using the Next Change toolbar button.
If not checked, DiffMerge leaves the caret where it was and does not highlight a
change. The user can then use the Next toolbar button to advance.

Clicking Restore Defaults restores all the fields on this (and only this) page to factory settings

SourceGear DiffMerge 3.2 User Manual

The Options Dialog 29

Rulesets
The Rulesets portion of the Options dialog controls whether Custom Rulesets are enabled and if so, how they are
chosen when a set of files is loaded into a File Diff or Merge window.

Rulesets enable custom per-file-type handling of various DiffMerge features, such as character encoding, end of line
conventions, and whitespace handling. These features can be triggered automatically by file suffix or interactively after
files are loaded.

Field

Meaning

Edit Default Ruleset

This default Ruleset is used when Custom Rulesets are not enabled or when no appropriate
Custom Ruleset exists. This button enables you to edit this default Ruleset, and opens the Edit
Default Ruleset dialog.

Enable Custom
Rulesets

Turns on Custom Rulesets. When OFF, the default Ruleset is used for all files.

Automatically Match

Each Custom Ruleset includes a list of file suffixes indicating the file types to which it applies.

30 The Options Dialog

SourceGear DiffMerge 3.2 User Manual

Suffixes

When set, DiffMerge uses the suffix list of each custom Ruleset (in order) to automatically find a
matching Ruleset.
For example, if you load a set of files "foo.cpp" and "bar.cpp", DiffMerge automatically selects the
"C/C++/C# Source" Custom Ruleset. If you load "foo.py" and "bar.py", DiffMerge automatically
selects the "Python Source" Custom Ruleset.

Ignore Case

Ignores the case of the file suffixes when matching.

Require Complete
Match

When the files in the set have different suffixes, its possible to take the first match, or to require all
of the files to match the same rule.
You probably don't want this turned on. Temp files often get a system-defined temp name rather
than the proper suffix. Enabling one file to match enables you to ignore the temp file suffix when
its being compared against a properly named file in your workspace.

Ask Me When
Nothing Matches

If no suffix match can be found, DiffMerge either uses the default Ruleset or asks you to pick one
from the Choose Ruleset dialog.

List of Custom
Rulesets and Buttons

The list box lists all of the currently defined Custom Rulesets. DiffMerge ships with Rulesets
predefined for C/C++/C# Source, VB Source, and several others. This list is ordered DiffMerge
searches for a match in the order listed. You can double-click a line item and edit/view the settings
for it (or click the Edit button to the right). Other buttons to the right enable you to perform the
standard operations Add/Delete/Clone and MoveUp/MoveDown.

Restore Defaults

Restores all of the fields on this (and only this) page to factory settings.

Editing Rulesets
DiffMerge includes a default Ruleset and a list of named custom Rulesets. The default Ruleset is used when the use of
custom Rulesets is disabled and when none of the custom Rulesets match the suffixes of the files being loaded in a
window.
The Edit Ruleset dialog enables you to modify the settings within a Ruleset. You can edit both the default Ruleset
(using the Edit... button at the top of the page) and individual custom Rulesets (using the Edit... button to the right of the
list of custom Rulesets).
When editing a custom Ruleset, the Edit Ruleset dialog is entitled "Edit Ruleset: <custom Ruleset name>" and has the
following 5 pages:

Name

Character Encodings

Line Handling

Content Handling

Lines to Omit

When youre editing the default Ruleset the Edit Ruleset dialog is entitled Edit Default Ruleset and only has the last 4
pages listed above.

Name
The Name page of the New Ruleset dialog enables the user to enter a human-readable Ruleset name that DiffMerge
uses to display on the Rulesets page of the Options dialog and in the file windows status bar. This name can be entered
in the top text box of the Name page.
The File Suffixes text box is a space-separated list of suffixes. When DiffMerge loads files it tests the suffixes on the
files against the ones in this list. If a Ruleset has a matching suffix for a particular file, then that Ruleset might be used.

SourceGear DiffMerge 3.2 User Manual

The Options Dialog 31

Character Encodings
Files on disk can be stored in various character encodings. When loaded, DiffMerge converts them into Unicode(TM)
before performing any analysis. This dialog enables you to specify the character encoding for files of this type, and
enables you to choose a specific encoding or request to be asked each time a document is loaded.

32 The Options Dialog

SourceGear DiffMerge 3.2 User Manual

Field

Meaning

Search for
Unicode BOM

When this is enabled DiffMerge looks for a Unicode Byte-Order-Mark when loading files; if a Unicode ByteOrder-Mark is present, DiffMerge informs you of the file's character encoding. If the Unicode Byte OrderMark is not present, DiffMerge uses the existing encoding options.

Use System
Local/Default
Encoding

Assume that files are encoded using the local system default character encoding. Use this if all files on your
system of this type have the same encoding as the local system.

Ask for Each

Window

Raises the Choose Character Encoding dialog and asks once for each set of files when a file window is
opened. This enables you to have files of this type be in multiple encodings -- but the same within a group of
files that you want to compare.

Ask for Each

File...

Raises the Choose Character Encoding dialog once FOR EACH FILE in a set of files when a file window is
opened. This enables maximum flexibility and lets you pick the encoding on a file-by-file basis. This enables
files with different encodings on disk to be compared.

Use Named
Character
Encoding Below

Enables you to select a fixed character encoding from the drop-down list below it. This encoding is used for
all files when this Ruleset is used.

Note: If a file is loaded in multiple windows, it will only be read from disk and decoded once. The value of the Character
Encoding settings in the active Ruleset of the first window is used. That is, if it is loaded into a second window, it shares
the in-memory copy and NOT the character encoding settings active in the second window.
After files are loaded, DiffMerge displays the character encoding(s) of the files in the status bar.

SourceGear DiffMerge 3.2 User Manual

The Options Dialog 33

Line Handling
This dialog enables you to adjust Overall Line Termination Handling as well as Overall Line Matching. Unless you have
specific needs, BOTH options should always be enabled.

Field

Meaning

Ignore/Strip All Line

Termination Characters

Different platforms use different line termination characters. Such differences can cause
two otherwise identical files to look like completely different files.
When enabled, this option changes all CR, LF, and CRLF characters to generic end-of-line
(EOL) markers before the difference analysis begins; line termination differences are not
indicated in any way. Therefore, files from different platforms with different EOL
conventions can be compared.
When disabled, the original CR, LF, and CRLF characters are preserved and used in the
analysis; the highlighting of Line Termination differences is context dependent.

Overall Line Matching

These 3 options direct DiffMerge to ignore case and whitespace during the vertical
alignment portion of the difference analysis. This allows DiffMerge to achieve the best text
alignment. Changes in case or whitespace are still indicated (regardless of the Detail
Level), but don't negatively affect overall alignment.

Content Handling
Within source code there are usually three types of content: string literals, comments, and everything else. Everything
else generally includes the functional part of the source code. These different types of content are called contexts.

String literals and comments are generally Matched Contexts; meaning that there is a specific pattern of
characters that delimit the beginning and ending of the context.

Content that matches a specific pattern is said to be in that context.

34 The Options Dialog

SourceGear DiffMerge 3.2 User Manual

Content that doesn't match a specific pattern (falls into the everything else category) is said to be in the Default
Context.

The Content Handling portion of the Edit Default Ruleset dialog enables you to create/edit/delete matched contexts
and set the attributes of the Default Context. Clicking Add or Edit takes you to the Edit Pattern dialog, where
matched contexts can be created or edited. The goal of matched contexts is to describe the features of the source code
language to identify contexts that should have different properties from the default context. Generally, this includes
string literals and comments; string literals should be more strict (everything is important) and comments are probably
more relaxed (the body of a comment is usually not as important as code, for example).

The fields under Default Context Guidelines are explained in the following table. These explanations also apply to the
Context Guidelines area of the Add/Edit Context dialog.
Field

Meaning

Classify Differences as
Important

This option determines if the overall context is important or unimportant. If important, you can refine
the context further to make commonly ignored things unimportant. Generally, all changes (except for
comments) should be marked important.

Line Termination is
Important

This option is only enabled if you elected to keep end-of-line chars in the analysis (not Ignore/Strip
EOLs). It determines how DiffMerge highlights differences in the EOL chars on a line.
Generally, this option is always disabled (because of the overall EOL handling).

Case is Important

This option determines how DiffMerge highlights differences due to changes in case. Generally, this
option should be turned on, unless you're in a case-insensitive language like VB.

Whitespace is
Important

This option determines how DiffMerge highlights differences due to changes in whitespace; this can
mean SPACES or SPACES and TABS depending on the next field.
In languages like C/C++ you should turn this option off for the default context because whitespace is
not significant within code. In languages like Python, you should turn it on, because leading whitespace
is significant.

Treat TABs as

This option is only enabled if the overall context is important, and if whitespace is not important. It

SourceGear DiffMerge 3.2 User Manual

The Options Dialog 35

determines whether TABs are equivalent to SPACES. Generally, this option should be turned on for
most languages.

Whitespace

Edit Context
A context is a mechanism for identifying portions of a document that should be specially handled. For example, string
and character literals and comments. The Edit Context box, accessible through the Content Handling dialog, enables you
to alter context boundaries and guidelines.

A context is defined as a start pattern and an optional end pattern. All of the text between that matching the start pattern
and that matching the end pattern and/or the end-of-line are considered to be in this context.
Patterns must be valid regular expressions. The end pattern may be omitted if Ends at EOL is checked. Set the Escape
Character if this context has a special character (such as a backslash) to prevent premature matching of the end pattern
or EOL.
Field

Meaning

Start Pattern

A Regular Expression that describes the start of a context. The text that matches the starting pattern is not
considered part of the matched context; only the content following it.

End Pattern

An Optional Regular Expression describing the end of the context. If the context ends at the end of the line,
leave this blank. The text matching the ending pattern is considered part of the matched context.

Escape
Character

Set if there is a special character (usually '\') that alters the interpretation of the next character.

Ends at EOL

Set if the context is terminated by the end-of-line.

At least 1 choice from End Pattern or Ends-at-EOL must be set; that is, you can either have an ending regular expression,
Ends-at-EOL, or both.
For information about Context Guidelines, refer to Edit Content Handling dialog.
Tip: Contexts and context highlighting are only enabled when in Lines-and-Character Detail Level mode.

36 The Options Dialog

SourceGear DiffMerge 3.2 User Manual

Lines to Omit
This dialog enables you to describe lines that should be completely omitted from the analysis. For example, this dialog
can be used when comparing reports to omit page and column headers and help the synchronization match up data in the
report rather than the headers. Everything on this page is optional.

Clicking Add or Edit takes you to the Edit Pattern dialog.

SourceGear DiffMerge 3.2 User Manual

The Options Dialog 37

Edit Pattern
This page of the Edit Default Ruleset dialog presents a list of active patterns.

The Pattern section of the dialog enables you to enter a regular expression to search for lines to omit. For convenience,
there are buttons to the right to supply patterns for commonly omitted items.
The Lines to Skip portion of the dialog indicates how many lines should be omitted with each match. Normally, this
should be 1.

38 The Options Dialog

SourceGear DiffMerge 3.2 User Manual

Detail Level
The Detail Level page of the Options dialog controls various file analysis parameters.

Clicking Restore Defaults restores all the fields on this (and only this) page to factory settings

Analysis Detail Level

Analysis Detail Level determines how the files are compared:

If Lines-Only mode is selected, DiffMerge compares the files line-by-line and does not perform any intra-line
highlighting/analysis.

In Lines-and-Character mode, DiffMerge performs the line-by-line analysis and then performs intra-line
analysis within the changes. Intra-line analysis is performed over the body of each change.

SourceGear DiffMerge 3.2 User Manual

The Options Dialog 39

Tip: Line-Only mode is faster than Lines-and-Character mode. Switch to Line-Only mode if youre working with large
files and having performance problems.

Multi-Line Intra-Line Analysis Detail Level

This feature controls how hard DiffMerge works to match up characters within a multiple line change.

If Complete mode is selected, the entire body (spanning all of the lines in the change) are essentially joined into
a single line before doing the character level analysis. This allows changes introduced by re-wrapping text to be
separated from actual changes to the text.

If Simple mode is selected, lines are joined like in Complete mode, but this is limited to avoid using an
excessive amount of time and memory.

If Disabled, DiffMerge does not attempt to join lines before doing the character level analysis.

For example, the following images show where a line of source code was broken across several lines in one version.
When Simple or Complete is enabled, only the whitespace is highlighted because DiffMerge matches up the words by
crossing the line boundaries.

When Disabled, DiffMerge sees this as five line change: there is a one line change (where text was deleted from the
end) followed by an insert of four lines of text. Since DiffMerge does not combine the lines in this mode, the two parts
are simply adjacent, but unrelated.

40 The Options Dialog

SourceGear DiffMerge 3.2 User Manual

Tip: Complete mode was the only mode available prior to version 3.2. This mode is very expensive. If you experience
performance problems, switch to Simple or Disabled.

Intra-line Smoothing Threshold

This field is only used when the Analysis Detail Level is set to Lines and Character. It causes small spans of equal
text within an intra-line change to be marked as part of the change. For example, if the following two lines
abcDEFgHIJklmnopqrstuvwxyz
abc123g456klmnopqrstuvwxyz
are matched up, you see that "DEF" changed to "123" and that "HIJ" changed to "456" with a "g" between them. When
the Intra-line Smoothing Threshold is set to 1, you see that "DEFgHIJ" changed to "123g456" as 1 change.
This feature doesn't change any results, just the coloring of short spans of text within lines.

Inter-line Smoothing Threshold

This field causes small groups of equal lines between two changes to be marked as part of the change. Inter-line
smoothing can be though of as "clumping" nearby changes into a single change. In source code a function frequently
consists of several lines of text, a blank line, several lines of text, a blank line, and so on. If someone inserts or changes a
big chunk of code, the blank lines can sync up and unrelated chunks of code can appear as blocks of changes. Setting the
Inter-Line Smoothing Threshold to 1 can cause these blocks of change to appear as 1 large change rather than
numerous little ones.
This feature is initially set to 0 (disabling it) because, in File Merge windows, Inter-line smoothing can cause adjacent
changes to be considered a conflict when the individual (unclumped) changes would not be. Enabling the feature
increases the likelihood that Auto-Merge will require manual follow-up, which may or may not be a good thing -- it's
somewhat questionable how far apart nearby changes should be to be considered independent changes. By increasing the
setting to 1 or 2, you may produce a few conflicts that will cause Auto-Merge to complain, but these are areas that you
probably want to examine anyway.
This field is used in both detail-level settings: Lines-Only and Lines and Character.

SourceGear DiffMerge 3.2 User Manual

The Options Dialog 41

Line Colors
The Line Colors page of the Options dialog enables you to change the default foreground and background highlighting
colors of each of the five different types of lines in File Windows. It is concerned with overall line coloring in both Lines
Only and Lines and Characters detail levels.

To change a color, all you need do is select the appropriate button. You are then taken to the standard color dialog box
where you can choose from pre-selected colors or pick your own.
The preview windows in the center of the page illustrate how your color choices will appear in File Diff and Merge
Windows when the detail level is set to Lines Only.
Clicking Restore Defaults restores all the fields on this (and only this) page to factory settings

42 The Options Dialog

SourceGear DiffMerge 3.2 User Manual

Intra-Line Colors
This page enables you to set the colors used to draw intra-line changes. The overall line colors (from the Line Colors
page) are shown for reference in the first and last columns. The buttons in the Foreground (Unimportant) column enable
you to change the de-emphasized foreground color used when an intra-line change is marked as unimportant, such as text
within a comment. The buttons in the Intra-line Background column enable you to change the background color of the
intra-line highlight.

To change a color, all you need do is select the appropriate button. You are then taken to the standard color dialog box
where you can choose from pre-selected colors or pick your own.
The preview windows in the center of the page illustrate how your color choices appear in File Diff and Merge Windows
when the detail level is set to Lines and Characters.
Clicking Restore Defaults restores all the fields on this (and only this) page to factory settings

SourceGear DiffMerge 3.2 User Manual

The Options Dialog 43

Other Colors
This page enables you to set the colors used to draw miscellaneous items in File Diff and Merge Windows.
The Other Colors page of the Options dialog is accessed by selecting Tools|Options and choosing Other Colors from
the left side of the Options dialog.

To change a color, all you need do is select the appropriately labeled box. You are then taken to a standard color dialog
box where you can choose from pre-selected colors or pick your own.
Clicking Restore Defaults restores all the fields on this (and only this) page to factory settings

44 The Options Dialog

SourceGear DiffMerge 3.2 User Manual

Folder Windows
The Folder Windows page of the Options dialog enables you to change the font used in windows, the font used when
the document is sent to the printer, and to select whether or not you want DiffMerge to automatically check for changed
files and folders when folder windows are activated.

Clicking Restore Defaults restores all the fields on this (and only this) page to factory settings.

SourceGear DiffMerge 3.2 User Manual

The Options Dialog 45

Folder Filters
If desired, Folder Windows can filter out temporary, binary, and other machine generated files and folders that are
normally produced as a by-product of software development. This page enables you to enable/disable this filtering and
set the list of file suffixes and folder names that should be omitted from the Folder Window display.
Please note that excluding these types of files and folders greatly increases the file system scanning speed and reduces
on-screen clutter.

File Suffix Filters: This section handles filtering files by suffix. The text field contains a space-separated list of suffixes
of files that should be excluded from the folder window. For example, you should filter out .EXE's and .DLL's because
they are binary files.
To turn off file suffix filtering, uncheck the Use File Suffix Filters checkbox.
Folder Filters: This section handles the filtering of entire sub-folders (and everything contained within them). The text
field contains a space-separated list of folder names that should be excluded from the folder window. For example, you
should filter out folders containing only binary files, such as a bin, lib, or obj directory generated by your compiler. You
should also exclude the SourceGear Fortress or Vault control file folders.

46 The Options Dialog

SourceGear DiffMerge 3.2 User Manual

To turn off sub-folder filtering, uncheck the Use Folder Filters checkbox.
You can turn off folder-filtering by clicking Ignore Folder Filters.
The Restore Defaults button restores all of the fields on this (and only this) page to factory settings.

SourceGear DiffMerge 3.2 User Manual

The Options Dialog 47

Folder Colors
This Folder Colors page of the Options dialog enables you to change the default foreground and background colors of
files, folders, and errors.

To change a color, all you need do is select the appropriate button. You are then taken to the standard color dialog box
where you can choose from pre-selected colors or pick your own.
Note: A Peerless file or folder is a folder that, when a list of files or folders is being compared, has no file or folder
in the comparison window.
The Restore Defaults button restores all of the fields on this (and only this) page to factory settings.

48 The Options Dialog

SourceGear DiffMerge 3.2 User Manual

Messages
This Messages page of the Options dialog enables you to choose which messages you want displayed by selecting them
from a list of choices.

In brief, these checked boxes ensure message boxes that provide either warnings or information display when the labeled
events take place. Each message box has a "Do not show again" option. These dialog fields indicate if the
warning/message is enabled or suppressed. You can use these fields to turn a message back on if, after the dialog has
displayed, you have selected the "Do not show again" option.
Clicking Restore Defaults restores all of the fields on this (and only this) page to factory settings.

SourceGear DiffMerge 3.2 User Manual

The Options Dialog 49

Windows Explorer Integration

This dialog is only available on Windows. It controls the Windows Explorer/Shell Integration feature. This feature is
optional and not required to use DiffMerge.
The Explorer/Shell Integration feature allows DiffMerge to add a menu item to Windows Explorer, the desktop, and the
Start Menu that allows you to launch DiffMerge on selected files and folders.

This feature is provided by an Explorer Integration library DLL that is shipped along with the DiffMerge executable.
This library must be separately installed (that is, registered with the system) before Explorer will use it.
This step is automatically performed by the DiffMerge .MSI installer.
This step is not performed if you installed DiffMerge using the .ZIP distribution.
This step is not performed if you received DiffMerge as part of a Vault or Fortress package.
If the Explorer Integration library is not registered with the system, the Install Now button will be enabled. Press this
button to register the library with the system and enable the feature. This is a system-wide registration and requires
administrator privileges.
Tip: If the Install Now button fails on Vista because of privilege problems, try launching
DiffMerge with administrator privileges. You can do this from Windows Explorer by right
clicking on the DiffMerge executable and selecting Run as Administrator.

50 The Options Dialog

SourceGear DiffMerge 3.2 User Manual

For the stand-alone version of DiffMerge, this is

C:\Program Files\SourceGear\DiffMerge\DiffMerge.exe.
For the version shipped with Fortress or Vault, this is
C:\Program Files\SourceGear\Fortress Client\sgdm.exe or
C:\Program Files\SourceGear\Vault Client\sgdm.exe.
Personal Settings: Once the Explorer Integration library is installed, you may enable or disable the feature for your
individual user account.

SourceGear DiffMerge 3.2 User Manual

The Options Dialog 51

External Tools
The External Tools page of the Options dialog allows you to direct DiffMerge to invoke external, third-party tools
when comparing and/or merging various types of files. This includes:
files given on the command line;
files interactively selected from the Select Files to Compare Dialog;
and files interactively selected from within a Folder Window.
External tools are triggered by file suffix so you can use it to configure other tools to handle file types, such as binary
files and word processing documents that DiffMerge doesnt support or for which youd just like to use a different tool
for. Tool suffix checking is performed before Ruleset suffix checking. DiffMerge searches for tools in the order listed
in the dialog and takes the first match. If no tool matches, DiffMerge creates a normal File Window
When DiffMerge is given a set of files on the command line with a matching tool configured, it will invoke the tool and
wait for it to exit before exiting; it will then exit with that tools exit status. When DiffMerge receives an interactive
request, it does not wait for the tool to complete.

Enable External Tools: Turns on/off the entire external tools feature.
Ignore Case When Matching File Suffixes: Indicates if case should be respected when matching files.

52 The Options Dialog

SourceGear DiffMerge 3.2 User Manual

Require Complete Match: Indicates if the suffixes for all of the files in the set must match or if only one needs to
match.
Tip: You probably dont want this turned on. Temp files often get a system-defined temp name rather than the proper
suffix. Turning off Complete Match allows you to ignore the temp file suffix when it is being compared against a
properly named file in your workspace.
Restore Defaults: Restores all of the fields on this (and only this) page to factory settings.
The listbox in the center lists all of the External Tools that are configured. By default, no external tools are configured.
You can use the buttons to the right of the list to create, edit, delete, and reorder tools.
For each External Tool configured, you can decide if the tool is enabled for 2-way diffs, 3-way merges, or both. You
can select different executables and command line argument templates for each mode.

Add/Edit External Tool

The Add/Edit External Tool dialog enables you to modify the settings for a tool.

Name
The Name page of the External Tool Dialog.

Name: The name field lets you enter a human-readable name for the tool. This name is for information only; it is
displayed in various places to help you identify the tool.
File Suffixes: The File Suffixes text box is a space-separated list of suffixes. When DiffMerge loads files it tests the
suffixes on files against the ones in this list. If a tool has a matching suffix for a particular file, then that tool might be
used.

SourceGear DiffMerge 3.2 User Manual

The Options Dialog 53

Diff
The Diff page controls settings for performing 2-way file diffs.

Enable External Tool for File Diffing: Determines if this tool will be used for 2-way file diffs.
Pathname to External Tool: This text field contains the pathname to the third-party executable. You can use the
button to browse for it.
Tip: On the Mac, you can give the path to either the application bundle (the foo.app folder) or the name of the
actual executable inside the application bundle (foo.app/Contents/MacOS/foo).
Command Line Arguments for External Tools: This text field contains the template for the command line to be used
with the executable. DiffMerge will perform token substitution on the field before invoking the command.
The buttons below the text field are for your convenience and can be used to insert the corresponding token at the
current insertion point into the text field.
Tip: It is highly recommended that you enclose these tokens in quotes so that whitespace in the titles and/or pathnames
are properly received by the external application.
DiffMerge defines the following substitution tokens for external 2-way file diff tools.
%LEFT_LABEL%
%RIGHT_LABEL%

The labels/titles for the left and right files.

When DiffMerge is handing off the initial set of files received on the command line, the
values for these tokens come from the /title1 and /title2 arguments, if given.
If not given on the command line or if you interactively cause DiffMerge to invoke an
external tool, the values for these tokens are the corresponding pathnames.

54 The Options Dialog

SourceGear DiffMerge 3.2 User Manual

%LEFT_PATH%
%RIGHT_PATH%

The pathnames for the left and right files.

Merge
The Merge page controls settings for performing 3-way file merges.

The descriptions for most of these fields are identical to the descriptions on the previous page for 2-way file diffs.
DiffMerge defines the following substitution tokens for external 3-way file merge tools.
%WORKING_LABEL%
%OTHER_LABEL%

%DEST_LABEL%

%WORKING_PATH%
%OTHER_PATH%
%BASELINE_PATH%
%DEST_PATH%

The labels/titles for the working (left) file and the other (right) files.
When DiffMerge is handing off the intial set of files received on the command line,
the values for these tokens come from the /title1 and /title3 arguments, if
given.
If not given on the command line or if you interactively cause DiffMerge to invoke an
external tool, the values for these tokens are the corresponding pathnames.
The label/title for the common ancestor (center) file. This comes from the /title2
argument when given. It falls back to the destination result pathname or the common ancestor
baseline pathname.
The pathnames for the working (left) and the other (right) files.
The pathname of the common ancestor/baseline (center) file.
The pathname where the merge result should be written. This comes from the /result
argument when given. It falls back to the baseline pathname.

SourceGear DiffMerge 3.2 User Manual

The Options Dialog 55

Printing

Printing in DiffMerge is standard. Select File|Print. The standard Print dialog box then displays, asking you to select the
printer, the number of copies, etcetera. (It is also possible to print from the Print Preview dialog.)
Each panel of a window is printed on a separate page; 2 pages across or 3 pages across as necessary. Page numbers are
augmented with the letters a, b, and c to help track the printed papers. Vertically, the display of files is synchronized
(with Voids used when necessary and printed as they are shown on screen) so that content is lined up on each page; that
is, you can place pages 10a and 10b side-by-side and the changes line up.
Lines that don't fit across a page are currently truncated. If long lines are a problem, print using landscape mode.

Print Preview Dialog

The Print Preview dialog is accessed by selecting File|Print Preview.

56 Printing

SourceGear DiffMerge 3.2 User Manual

Four related buttons are listed below the Print button, each with a fast forward or rewind symbol. Assuming the
document has multiple pages, these buttons enable you to advance one page or backup one page, advance all the way to
the end of the document, or backup to the beginning.
Clicking the Goto button opens the Goto Page dialog.
Line Color and Line Numbers can be adjusted from Options|Line Colors and Options|Other Colors.
Likewise, the printing font can be changed from the Options dialog.
The Size Selection window selects the size at which you view the document. To change the documents display size,
click the window and select a size.

SourceGear DiffMerge 3.2 User Manual

Printing 57

There are a number of features that can be adjusted when you are preparing a document for printing.
Headers

Headers are printed on each page, providing the (elided) pathname of the file being compared.

Page Numbers

Each panel is printed on a separate page. Page numbers are augmented with a, b, and c to aid in
easier placement of the printed pages.

Footers

Footers provide a summary of the options and settings in effect at the time of the printing. This
includes the current Ruleset in use, the Display Mode, and the Tab Stop setting.

Line Numbers

If the Line Numbers option is turned on in the window, the output also has line numbers. (To turn on
the line numbers see Show Line Numbers.)

Line Colors

Lines with changes are printed in color and in bold. Line detail (whether whole lines are highlighted
or intra-line changes are highlighted) depends upon the Detail Level you select in the Options dialog.
It is possible to change File Colors from the Options Dialog.

The Goto Page Dialog

The Goto Page dialog is accessed from the Print Preview dialog: open the File|Print Preview and click Goto. Its
primarily useful when youre dealing with a very long document. When the Goto Page dialog appears, it enables you to
select the page you wish to view by typing in its number in the blank area of the dialog box.

58 Printing

SourceGear DiffMerge 3.2 User Manual

Command Line Arguments

diffmerge.exe [ options ] [ pathname1 [ pathname2 [ pathname3 ] ] ]

Option

Meaning

h, help

Raises usage dialog and exits.

c, caption

Descriptive caption for the application title bar of the first window
opened.

Example:
/caption="Hello World!"
m, merge
Only applies to File Merge Windows.
nosplash

Run "Merge to Center Panel" immediately after loading files in the

first window opened.
Suppresses splash screen.

Only applies when no pathnames are

given.
r, result
Only applies when 3 source pathnames
are given on the command line.

Specifies alternate pathname for saving the merge result from the
first window. If not specified, the merge result (if saved) will
overwrite the center file.

Example:
/result="C:merge_result.txt"
ro1

[DEPRECATED] Unused.

ro2

Treat the second pathname as read-only. Prevents editing in the first

window opened. (See "Viewer Mode".)

Only applies when 2 or 3 pathnames are

given on the command line.
ro3

[DEPRECATED] Unused.

shex

Shell/Extension flag; forces the Open Files or Folders dialog to appear

(even when not necessary) before opening the first window. This
allows you an opportunity to swap the pathnames if necessary.

(Only available on Microsoft Windows.)

t1, title1
Example:

Sets the display title for the first pathname given on the command
line.

/title1="Version 12 (foo.cpp)"

SourceGear DiffMerge 3.2 User Manual

Command Line Arguments 59

t2, title2
t3, title3
Only applies to 3-way windows.

Sets the display title for the second pathname given on the command
line.
Sets the display title for the third pathname given on the command
line.

Batch Option

Meaning

d, diff

Compare two files and write results to an output file rather than opening a
window.

Example:
/diff=diff.output

The file is only created if there are differences to report.

The Exit Status is:
0 - if the input files are identical;
1 - when they are different;
2 - when there are file errors; and
-1 (255) - for command line errors.

u, unified

Write the /diff output file in UNIFIED format rather than TRADITIONAL
format.

Arguments

Meaning

pathname1, pathname2, pathname3

A set of 2 or 3 files or 2 folders to open in the first window.

For File Diff Windows, pathname1 is placed in the left panel and
pathname2 is placed in the right panel. pathname2 will be editable.
For File Merge Windows, pathname1 is placed in the left panel,
pathname2 is placed in the middle panel, and pathname3 is placed in the
right panel. pathname2 is considered to be the common ancestor.
For Folder Diff Windows, pathname1 is placed in the left panel and
pathname2 is placed in the right panel.

Command options have a long and short form and may either be prefixed by a '/' or a '-' depending upon your platform.
For example: -h, -help, --help, /h, or /help. For options that require values, they must have a COLON, EQUAL,
or SPACE separator character between the keyword and the value. For example, /caption="Hello World!".

For example:
diffmerge /t1="Baseline" /t2="My Working Version" c:/baseline/foo.cpp
c:/work/foo.cpp

diffmerge /t1="My Working Version" /t2="Merge Result" /t3="Repository

Version" /r="c:\merge_result.cpp" c:/work/foo.cpp c:/baseline/foo.cpp
c:/current/foo.cpp

60 Command Line Arguments

SourceGear DiffMerge 3.2 User Manual

Integration with Third-Party

Software

DiffMerge can be configured as an external compare / merge tool with various third-party version control systems.
Usually this just involves formatting the correct command line template string in the packages options dialog. Here are
instructions for the packages that we have information about.

Microsoft TFS
Information on configuring an external diff/merge tool can be found at:
http://msdn2.microsoft.com/en-us/library/ms181446.aspx
This document describes how to configure tools based upon file suffix. A * can be used for the suffix to change the
default tool settings.
For a listing of the arguments used to build the command line string, see James Mannings blog:
http://blogs.msdn.com/jmanning/articles/535573.aspx
The arguments for comparing two files or two versions of a file should be:
/t1=%6 /t2=%7 %1 %2
With this command line, original version (%1) will be in the left panel and the modified version (%2) will be in the
right panel. If you want to limit yourself to strictly viewing, rather than editing, the changes, add /ro2 to the beginning
of the above command line.
The arugments for merging two versions of a file from a common ancestor should be:
/m /r=%4 /t1=%7 /t2=%8 /t3=%6 /c=%9 %2 %3 %1
With this command line, your changes (%2) will be in the left panel, the common ancestor (%3) will be in the center
panel, and their changes (%1) will be in the right panel. When you save your merge changes, they will be written to
the merge result (%4) file.

TortoiseSVN
Information on configuring an external diff/merge tool can be found in
http://tortoisesvn.net/docs/release/TortoiseSVN_en/tsvn-dug-settings.html#tsvn-dug-settings-progs

SourceGear DiffMerge 3.2 User Manual

Integration with Third-Party Software 61

The arguments for comparing two files or two versions of a file should be:
/t1=%bname /t2=%yname %base %mine
With this command line, original version (%bname) will be in the left panel and the modified version (%mine) will
be in the right panel. . If you want to limit yourself to strictly viewing, rather than editing, the changes, add /ro2 to the
beginning of the above command line.
The arugments for merging two versions of a file from a common ancestor should be:
/m /r=%merged /t1=%yname /t2=%bname /t3=%tname /c=%mname %mine %base
%theirs
With this command line, your changes (%mine) will be in the left panel, the common ancestor (%base) will be in the
center panel, and their changes (%theirs) will be in the right panel. When you save your merge changes, they will be
written to the merge result (%merged) file.

62 Integration with Third-Party Software

SourceGear DiffMerge 3.2 User Manual

Regular Expressions

DiffMerge performs various searches and pattern matches using the RegEx regular expression library from Henry
Spencer. DiffMerge uses the Advanced Regular Expressions that it defines. The library implements POSIX regular
expressions and also supports Unicode and some Perl5 extensions.
**********************************************************************
Copyright (c) 1998, 1999 Henry Spencer. All rights reserved.
Development of this software was funded, in part, by Cray Research Inc., UUNET Communications Services Inc., Sun
Microsystems Inc., and Scriptics Corporation, none of whom are responsible for the results. The author thanks all of
them.
Redistribution and use in source and binary forms -- with or without modification -- are permitted for any purpose,
provided that redistributions in source form retain this entire copyright notice and indicate the origin and nature of any
modifications.
I'd appreciate being given credit for this package in the documentation of software which uses it, but that is not a
requirement.
THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING,
BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL HENRY SPENCER BE LIABLE FOR ANY
DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY
OF SUCH DAMAGE.
**********************************************************************
wxWindows adopted the code out of Tcl 8.4.5. Portions of regc_locale.c and re_syntax.n were developed by Tcl
developers other than Henry Spencer; these files bear the Tcl copyright and license notice:
**********************************************************************
This software is copyrighted by the Regents of the University of California, Sun Microsystems, Inc., Scriptics
Corporation, ActiveState Corporation and other parties. The following terms apply to all files associated with the
software unless explicitly disclaimed in individual files.
The authors hereby grant permission to use, copy, modify, distribute, and license this software and its documentation for
any purpose, provided that existing copyright notices are retained in all copies and that this notice is included verbatim in
any distributions. No written agreement, license, or royalty fee is required for any of the authorized uses. Modifications
to this software may be copyrighted by their authors and need not follow the licensing terms described here, provided
that the new terms are clearly indicated on the first page of each file where they apply.

SourceGear DiffMerge 3.2 User Manual

Regular Expressions 63

IN NO EVENT SHALL THE AUTHORS OR DISTRIBUTORS BE LIABLE TO ANY PARTY FOR DIRECT,
INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OF THIS
SOFTWARE, ITS DOCUMENTATION, OR ANY DERIVATIVES THEREOF, EVEN IF THE AUTHORS HAVE
BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
THE AUTHORS AND DISTRIBUTORS SPECIFICALLY DISCLAIM ANY WARRANTIES, INCLUDING, BUT
NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
PURPOSE, AND NON-INFRINGEMENT. THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, AND THE
AUTHORS AND DISTRIBUTORS HAVE NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT,
UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
GOVERNMENT USE: If you are acquiring this software on behalf of the U.S. government, the Government shall have
only "Restricted Rights" in the software and related documentation as defined in the Federal Acquisition Regulations
(FARs) in Clause 52.227.19 (c) (2). If you are acquiring the software on behalf of the Department of Defense, the
software shall be classified as "Commercial Computer Software" and the Government shall have only "Restricted
Rights" as defined in Clause 252.227-7013 (c) (1) of DFARs. Notwithstanding the foregoing, the authors grant the U.S.
Government and others acting in its behalf permission to use and distribute the software in accordance with the terms
specified in this license.
**********************************************************************

64 Regular Expressions

SourceGear DiffMerge 3.2 User Manual

SourceGear License Agreement

IMPORTANT READ CAREFULLY. This License Agreement (Agreement) is a legal agreement between you
(either an individual or a single entity) and SourceGear LLC for SourceGear DiffMerge which includes
computer software and online or electronic documentation and may include associated media and printed
materials (SOFTWARE PRODUCT or SOFTWARE). By installing, copying, or otherwise using the
SOFTWARE PRODUCT, you agree to be bound by the terms of this Agreement. If you do not agree to the
terms of this Agreement, do not install or use the SOFTWARE PRODUCT.
SOFTWARE PRODUCT LICENSE
The SOFTWARE PRODUCT is protected by copyright laws and international copyright treaties, as well as
other intellectual property laws and treaties. The SOFTWARE PRODUCT is licensed, not sold.
1. GRANT OF LICENSE. This Agreement grants you certain limited, non-exclusive rights. SourceGear LLC
reserves all rights not expressly granted to you.
2. COPYRIGHT. All rights, title, and copyrights in and to the SOFTWARE PRODUCT (including, but not
limited to, any images, photographs, animations, video, audio, music, text, and "applets" incorporated into the
SOFTWARE PRODUCT) and any copies of the SOFTWARE PRODUCT are owned by SourceGear LLC or
its suppliers. The SOFTWARE PRODUCT is protected by copyright laws and international treaty provisions.
Therefore, you must treat the SOFTWARE PRODUCT like any other copyrighted material, except that you
may make one copy of the SOFTWARE PRODUCT solely for backup or archival purposes. You may not copy
the printed materials accompanying the SOFTWARE PRODUCT.
3. DESCRIPTION OF OTHER RIGHTS AND LIMITATIONS.
3a. Limitations on Reverse Engineering, Decompilation, and Disassembly. You may not reverse engineer,
decompile, or disassemble the SOFTWARE PRODUCT, except and only to the extent that such activity is
expressly permitted by applicable law notwithstanding this limitation.
3b. Rental. You may not rent or lease the SOFTWARE PRODUCT.
3c. Software Transfer. You may permanently transfer all of your rights under this Agreement, provided you
retain no copies, you transfer all of the SOFTWARE PRODUCT (including all component parts, the media and
printed materials, any upgrades, and this Agreement), and the recipient agrees to the terms of this
Agreement. If the SOFTWARE PRODUCT is an upgrade, any transfer must include all prior versions of the
SOFTWARE PRODUCT.
3d. Termination. Without prejudice to any other rights, SourceGear LLC may terminate this Agreement if you
fail to comply with the terms and conditions of this Agreement. In such event, you must destroy all copies of
the SOFTWARE PRODUCT and all of its component parts.
3e. Distribution. You may not distribute this product, or any portion thereof, or any derived work thereof, to
anyone outside your organization.
4. EXPORT RESTRICTIONS. You agree that neither you nor your customers intend to or will, directly or
indirectly, export or transmit the SOFTWARE PRODUCT or related documentation and technical data to any

SourceGear DiffMerge 3.2 User Manual

SourceGear License Agreement 65

country to which such export or transmission is restricted by any applicable U.S. regulation or statute, without
the prior written consent, if required, of the Bureau of Export Administration of the U.S. Department of
Commerce, or such other governmental entity as may have jurisdiction over such export or transmission.
5. U.S. GOVERNMENT RESTRICTED RIGHTS. The SOFTWARE PRODUCT and documentation are
provided with RESTRICTED RIGHTS. Use, duplication, or disclosure by the Government is subject to
restrictions as set forth in subparagraph (c)(1)(ii) of The Rights in Technical Data and Computer Software
clause at DFARS 252.227-7013 or subparagraphs (c)(1) and (2) of the Commercial Computer Software Restricted Rights at 48 CFR 52.227-19, as applicable. Manufacturer is SourceGear LLC, an Illinois LLC.
MISCELLANEOUS
This Agreement is governed by the laws of the State of Illinois. Should you have any questions concerning
this Agreement, or if you desire to contact SourceGear LLC for any reason, please access our website at
http://www.sourcegear.com or contact us at [email protected].
NO WARRANTIES. To the maximum extent permitted by applicable law, SourceGear LLC expressly
disclaims any warranty for the SOFTWARE PRODUCT. The SOFTWARE PRODUCT and any related
documentation are provided "as is" without warranty of any kind, either express or implied, including, without
limitation, the implied warranties of merchantability or fitness for a particular purpose. The entire risk arising
out of use or performance of the SOFTWARE PRODUCT remains with you.
LIMITATION OF LIABILITY. SourceGear LLC entire liability and your exclusive remedy under this Agreement
shall not exceed five dollars (US $5.00).
NO LIABILITY FOR CONSEQUENTIAL DAMAGES. To the maximum extent permitted by applicable law, in
no event shall SourceGear LLC or its suppliers be liable for any damages whatsoever (including, without
limitation, damages for loss of business profit, business interruption, loss of business information, or any other
pecuniary loss) arising out of the use of, or inability to use, this SourceGear LLC product, even if SourceGear
LLC has been advised of the possibility of such damages. Because some states/jurisdictions do not allow the
exclusion or limitation of liability for consequential or incidental damages, the above limitation may not apply
to you.
-------------------------------------SourceGear is a registered trademark of SourceGear LLC.
SourceGear DiffMerge is a trademark of SourceGear LLC.
Copyright (C) 2003-2008 SourceGear LLC. All rights reserved.

66 SourceGear License Agreement

SourceGear DiffMerge 3.2 User Manual

SourceGear DiffMerge 3.2 User Manual

67