winmerge.org

WinMerge 2.12 Quick Tour

Abstract

WinMerge is an Open Source differencing and merging tool for Windows. Use it to detect changes between files and folders, and then to merge changes selectively. You can use WinMerge by itself, or launch it from a version control system or another application.

When you compare two files or folders, the result is displayed in the WinMerge window. The WinMerge window's visual display and functions are designed to help you see differences between your targets, and to merge selected differences if you want to.

In a file comparison: WinMerge shows differences between lines. The built-in text editor provides syntax highlighting for several programming languages and other file formats.

In a folder comparison: WinMerge indicates various kinds of differences between the files that the folders contain.

Take this brief, guided tour if you are considering installing WinMerge, or if you just want to see what the tool looks like and what you can do with it. The topics below describe the main WinMerge features. They include some simple examples of comparing files and folders, and merging differences between them.

This tour just scratches the surface. For detailed information and guidance about using WinMerge, see the Help that is installed with WinMerge and available on our Web site.


Starting WinMerge compare operations
Drag and drop
Windows Explorer context menu shortcuts
Select Files or Folder dialog
Command line
Version control systems
Comparing Files
The File Compare window
Navigating line differences
Merging differences in files
Comparing Folders
The Folder Compare window
Navigating folder differences
Comparing subfolders
Merging folder differences

Starting WinMerge compare operations


Every WinMerge compare operation has two targets: either two files or two folders. WinMerge makes it easy to select targets and launch comparisons from different places in your Windows environment. Here are some commonly used methods:

Drag and drop

Select two files or two folders in Windows Explorer and drag them to the WinMerge shortcut on your desktop, or into the WinMerge window if it's already open.

Drag and drop to WinMerge Desktop icon
[Note] Note

If you drop only one file or folder into the WinMerge icon or window, WinMerge opens the the section called “Select Files or Folder dialog”, where you can specify the other target.

Windows Explorer context menu shortcuts

WinMerge has an option that adds a WinMerge shortcut to the context menu when you select one or two files or folders in Windows Explorer. Choosing the shortcut opens WinMerge and compares the selected items:

Windows Explorer basic context menu integration

For even more flexibility, you can replace the basic WinMerge shortcut with a set of advanced shortcuts. Use these shortcuts to select objects separately, even from different Explorer folders or windows. The next screen shot shows a typical sequence: we choose the first compare target in one Explorer view, then the second target in another Explorer view.

Windows Explorer advanced context menu integration

Select Files or Folder dialog

For maximum flexibility in launching compare operations, click FileOpen in the main WinMerge window to open the Select Files or Folders dialog:

Select Files or Folders window

This dialog lets you browse anywhere for the files or folders to compare. Alternatively, you might choose a recently-used file or folder from the Left and Right drop-down controls. You can even drag a file or folder from Windows Explorer into the Left or Right field. A message prompts you if either target is not found, or if you entered a combination of file and folder (WinMerge can't compare files to folders!) in the two fields.

The dialog contains several options to tailor your compare operation, including these:

Filter

Use this option to apply a filter to narrow the scope of the comparison. There two kinds of filters:

File filters: Include or exclude files that match regular expressions. For example, the expression ^test matches files that start with the string, test, like testheaders.h. WinMerge installs a number of filter files that specify commonly-excluded files for various languages, like C#, C++, and Visual Basic. You can edit these files and, of course, add your own.

Line filters: Ignore lines within files that match patterns. For example, the expression ^[1-5]00 ignores lines beginning with numbers 100, 200, 300, 400, and 500.

WinMerge provides the Filters dialog for creating and managing filters.

Include Subfolders

This option lets you control the depth of a folder comparison. Enabling it compares all folder levels, which might take a while if there are a lot of files. Disable it to compare only the top level of the target folders. This is the fastest option, and you can “drill down” into nested folders later in the Compare Folders window.

Command line

The WinMerge CLI includes commands with a full set of parameters and options that you can use in a script or Command Prompt window to launch comparisons. This example compares two folders recursively and displays the result in the WinMerge window:

WinMergeU /r C:\folder1 C:\folder2

Version control systems

If you run TortoiseSVN, TortoiseCVS, or Rational ClearCase, you can configure your version control system to open WinMerge directly. That is, if you compare files using one of these VCS tools, WinMerge opens instead of the tool's native diff utility.

[Note] Note

Another handy VCS integration automatically launches your version control system's checkout dialog whenever you change a managed file in the WinMerge window. This integration works with version control systems that lock files, specifically ClearCase and Visual Source Safe.

Comparing Files


When you compare two files, WinMerge shows the differences between their lines. To demonstrate comparing and merging files, consider these two small text files named File1 and File2:

File1: 

You can cage a swallow,
can't you? 
But you can't swallow 
a cage, can you?

File2: 

You can cage a swallow.
But you can't swallow 
a cage. Can you?

The File Compare window

If you launch a WinMerge compare operation on two files, the File Compare window opens. This screen shot compares our two sample files:

Compare Files screen shot

The File Compare window makes it easy to see differences between lines in your files. It also has special functions for merging different lines from one file to the other, and basic editing capabilities for more detailed merging within lines. Notice these basic features of the File Compare window:

  • In the bottom right corner of the window, the status bar tells you how many differences WinMerge detects.

    The Location pane indicates where the differences are located in the files. The Location pane is helpful for working with long files, where you can't see all the differences at once in the File panes.

  • Differences are marked in the File panes by a gold background color. In this comparison, the first difference is a block of two lines; the second difference is a single line at the end.

  • Notice that the first difference has an extra blank line on the right side. Why does this blank line appear, since it doesn't exist in the source file?

    The empty line is a placeholder in WinMerge that does not change the source file. WinMerge inserts blank lines on one side of a difference whenever the other side has more lines. The extra lines, marked with a gray background color by default, keep the left and right sides vertically aligned for ease of comparison. That is, every difference begins on the same line in the File panes, even when they are on different lines in the source files. Without this feature, files of different lengths would be hard to compare.

  • The third line is identical in both files, so it has no difference color (its background is white).

  • Within differences, WinMerge highlights the text that makes the lines different. By default, different words are highlighted. To see more detail you can highlight changes at the character level; to see less, you can turn off all highlighting within lines.

[Note] Note

The WinMerge main window can contain multiple File Compare (and Folder compare) windows. Each File Compare window displays the result of a single comparison, representing the two files in the left and right File panes. In our screen shot, the File Compare window is maximized within the main window:

Navigating line differences

In the File Compare window you can use standard mouse and cursor actions to select and edit text in either File pane. But in WinMerge, working with text and working with differences are not the same thing. WinMerge provides special functions to navigate differences.

For example, click anywhere in an area that is marked as a difference, then click the Current Difference button Current Difference button in the toolbar.

The next two screen shots show the first difference in our sample comparison, after it's selected. When you select a difference, several things happen:

  • The Selected Difference background color (red by default) highlights the difference in the File panes. The Location Pane also highlights the selected difference and marks its location with arrows. :

    Difference selected in Compare Files panes
  • The selected difference is loaded in the Diff pane, where you can examine it in isolation from other differences.

    Compare Files Diff Pane
  • All the merge buttons in the toolbar are enabled:

  • The status bar confirms which difference is selected.

Merging differences in files

You can merge differences at two levels in the File Compare window:

Line-level differences

As we have seen, a difference includes one or more lines. Use the WinMerge merge functions to copy an entire selected difference from one side to the other. For example, click the Copy Right and Advance button Copy Right and Advance button.

Compare Files window after merge

Notice the changes:

  • The first difference is gone: the lines are now identical and have no difference color.

  • WinMerge automatically selects the next difference, skipping over the identical line. The Location Pane also moves its indicator.

  • The status bar indicates that only one difference remains.

You can see that the navigation and merge functions provide a good way to systematically step through all the differences in a comparison.

Differences within lines

Instead of merging entire differences using the Merge functions, you can change text within them by manually editing either file directly in the File Compare window. For example, if you don't want to use either side of the first difference, you can delete the line. Or, you might replace “words” on the right side with “text”.

After you finish merging, you can click FileSave to save changes to both sides. Or, to save just one side, click FileSave Left or FileSave.

This was a trivial example — there were only two differences and we only merged one of them. But you can use the methods shown here to navigate and merge line differences between files of any length.

Comparing Folders


In addition to comparing files in WinMerge, you can compare the contents of folders. WinMerge shows which files are different, and provides functions to merge files between folders.

The Folder Compare window

If you launch a WinMerge compare operation on two folders, the Folder Compare window opens:

Folder Compare window

The Folder Compare window lists the files and subfolders found in the target folders. Each row compares a file or subfolder in the two selected folder targets. As with the File Compare window, the targets are represented on “left” and “right” sides.

These columns tells you whether corresponding right and left items in each row are identical, different, or exist on only one side. The asterisk in either the left or right date highlights the more recent date. The icons in the Filename column provide visual cues for each type of file, like text or binary files, and how the two sides are different. Icons are also used to mark files and folders that are found only on one side.

The columns are sortable. By default, rows are sorted by filename in descending alphabetical order. Click the Filename column title to reverse the sorting. Or, maybe you're only interested in rows that are different. If so, click the Comparison result column title to sort by result type. This groups different files together so they're easy to see.

If you want to display more information, a simple customization lets you add additional columns, including file creation time, file encoding type, file size, and even the number of differences found.

The Folder Compare window supports common operations on files, like editing, copying, deleting, moving, and renaming (moving is equivalent to a copy operation followed by a delete). You can use these file operations and WinMerge functions to merge the contents of folders. You can also open files using associated programs or external editors. You can even launch file compare operations on individual files from the Folder Compare window.

The Navigator up arrow button up arrow button at the top of the Filename column navigates to the parent folder of each target.

As we mentioned earlier, the WinMerge main window can contain multiple Folder Compare or File Compare windows, and each Compare window displays the result of a single comparison. In the preceding screen shot, the File Compare window is maximized within the main window:

Navigating folder differences

To navigate differences at the folder level:

  • Use conventional keyboard and mouse actions to move between rows. To select a difference, simply click its row.

  • Use the Difference buttons in the toolbar to select differences systematically. For example, click the Next Difference button Next Difference button in the toolbar (or press Alt+Enter) to select the next row that is different, automatically skipping identical rows.

Comparing subfolders

So far we have looked at a non-recursive comparison, which includes files only in the root of the two folders you select, not any subfolders that they contain. To compare their subfolders, you have to launch a new compare operation. For example, in the preceding comparison, double-click the Common folder icon to open a new File Compare window that compares the two Common folders.

WinMerge can also compare folders recursively. A recursive comparison includes all the files in all subfolders, so you don't need to launch separate compare operations to navigate nested folders.

For targets with many nested folders and files, a recursive comparison can can take longer than a non-recursive comparison, and the result can be harder to read. In this case, consider displaying the results of recursive comparisons in a hierachical tree view instead of the default tabular view. Folders are initially collapsed for a compact, readable display — expand just the ones whose contents you want to see:

Folder Compare window

Merging folder differences

Merging in the Folder Compare window involves either copying items (files or folders) between folders, or deleting items.

For example, suppose you want to synchronize two folders. In the preceding screen shot, you can tell from the asterisk that the left version of AboutDlg.h is more recent. So, to merge AboutDlg.h select the row and click the Copy Right button Copy Right button in the toolbar.

When you merge a file or folder, the value in the Comparison result column changes to Identical.

Of course, you might not always want to merge entire files or folders. For example, you might want to merge selected differences within the files, or to examine the differences within files before merging them. In such cases, you can double-click a file to launch a file comparison. WinMerge displays the result in a new File Compare window, where you can see and merge the line-level differences.