Comparing and merging text files

The left and right File panes show the text contents and differences of the two files being compared. The File panes are the main area for navigating and merging differences, and also allow you to edit the text directly. This section describes the features that support these actions, and ways that you can customize the File panes.

2.1.3. Line difference highlighting

Sometimes it's useful to highlight not just difference blocks, but also the text within them that is changed. You can disable or enable them in two ways:

• Set all View line differences options in the Options dialog Editor page.

• Click View → View line differences to toggle line differences on or off.

	Note
	Remember that WinMerge navigation and merging functions (like Next Difference or Copy Left) work on difference blocks, not on line differences within them.

This section describes how line differences are detected and marked. Note that the effect of these options is also affected by your current whitespace settings in the Options dialog Compare page.

Word-level line differences

The following examples show how word-level line differences are displayed with each of the whitespace settings:

Example 1. Line differences with Whitespace: Compare

WinMerge detects all different words and spaces:

Example 2. Line differences with Whitespace: Ignore change

Multiple spaces and tabs are treated the same as a single space. In the example, the extra space between the last two words is not marked:

Example 3. Line differences with Whitespace: Ignoring all

No spaces between words are compared, so these lines are treated as identical:

Character-level line differences

A character-level line difference includes the first and last different characters in a word, and all the characters between them. A single character-level difference can span adjacent words. The following example illustrates:

	Note
	As with word-level line differences, character highlighting varies according to how WinMerge is configured to detect word breaks. In the example, the extra space after the word cure in file2 is highlighted only if whitespace is compared.

Breaks for words or character

Words and characters in line differences can be separated by whitespace, or by a combination of whitespace and punctuation. Whitespace (the default) is the typical choice for comparing most text files. All the preceding line difference examples use whitespace to break words and characters.

In some cases it's useful to break at punctuation. For example, the next screen shot compares a comma-separated list. To highlight meaningful line differences, we have enabled Break at whitespace or punctuation in the Options dialog Editor page.

2.1.4. File pane editing features

Although WinMerge is a not a full-featured editor or IDE, it does provide basic editing functions, like Undo and Redo, Find and Replace, and Goto. These basic editing tasks are often needed during merging (for example, to change text within differences). You can edit in the active File pane (remember, click in a pane to make it active). Changes are not written to a file until you save a pane to a result file.

WinMerge editing features also include syntax highlighting. This optional feature supports several file formats, and you can configure the colors used. Note that syntax highlighting is not applied within differences, as the preceding screen shot shows.

	Tip
	Make sure that Automatic rescan is enabled, as described in Rescanning files. If it is not, manually refresh your view (press F5) before and after editing a file, to ensure that WinMerge difference detection is up to date.

2.1.6. File pane margins

The File panes have optional gray margins that show line numbers and some symbols. To show or hide the margins, clicking View → View Margins. If you are using multiple File Compare windows, you can control margins for each window independently. The margin can show any or all of these features:

• Line numbers, if View → View Line Numbers is enabled.

• Bookmarks, if Edit → Bookmarks is enabled. A bookmark is a blue circle, in the margin next to a line, that you can make WinMerge remember and return to.

  • To set a bookmark on a line, double-click in its margin (or press (Ctrl+F2). The same action deletes an existing bookmark.

  • To navigate bookmarks, click Edit → Bookmarks and choose Next or Previous.

  • Double-click a single bookmark to delete it (or press (Ctrl+F2).

  • Click Edit → Bookmarks → Clear All Bookmarks to delete all bookmarks.

• Word wrap arrow symbols, if View → Wrap Lines is enabled.

The following screen shot shows a margin with bookmarks and word wrap enabled. Without line numbers, the margin width is minimal.

The next screen shot shows a margin with bookmarks and line numbers enabled. Notice that the margin is wider. In fact, the margin is wide enough for the largest line number. Thus, the margins for large files with many lines can be quite wide.

The WinMerge toolbar and menus provide a range of functions to navigate, select, and merge differences within files.

	Note
	WinMerge shortcuts have the same names and buttons whether you open a Folder Compare or File Compare window. However, the functions behave differently: with a File Compare window, the functions operate on differences within files, not on differences within folders.

The difference functions you can use depend on your context, which often changes as you work. This means that a function is available only when its operation is possible for a given location or other condition in your WinMerge environment. For example, if you click in a line of text within a difference, you might notice several navigation and merge buttons become enabled in the toolbar. If you click in another area of text that is not within a difference, these functions become unavailable.

Difference functions are available in the WinMerge toolbar,and also through these alternate mechanisms:

Difference functions are described in Navigating differences and Merging differences, later in this topic. Quick start and Overview of file comparing and merging provide examples of comparing and merging.

The Location pane, to the left of the File panes, maps the entire length of the compared files into two vertical bars (corresponding to the left and right File panes). It is especially useful for working with files that are too long to easily navigate in the File panes.

The Location pane shows several kinds of items:

The Location pane's context menu contains these shortcuts:

The Diff pane shows the contents of the two sides of a selected difference.

When you select a difference, the two versions are loaded in the upper and lower sides of the Diff pane. In this way, the Diff pane confirms which lines are included in a difference, and lets you examine them in isolation from the rest of the file.

You can merge differences directly in the Diff pane by right-clicking in either the top or bottom side and choosing Copy to Right or Copy to Left.

Each File pane contains a status bar at the bottom. The status bar contains several panes with different types of information about the document and your location in it:

When a File Compare window is open, the WinMerge window status bar shows one of these messages about the compared files:

By default, the WinMerge window displays a single File Compare window. If you start another file comparison (by clicking File → Open and selecting another pair of files) while a File Compare window is currently open, the current File Compare window is closed, unless WinMerge detects unsaved changes in the left or right file. If you have modified either file, WinMerge prompts you to save or discard your changes before opening a new File Compare window.

For example, in the next screen shot WinMerge gives you a chance to save changes detected in the right side file:

If you plan to work with multiple compare operations simultaneously, consider setting (checking) the Enable multiple compare windows for File compare option, which is disabled by default. With this option enabled, you can open multiple File Compare windows without the intervening Save step.

By default, Compare windows are displayed as individually resizeable child windows within the WinMerge window, like this:

If you maximize your Compare window (by clicking its Maximixe button), the window fills all the available space in the WinMerge window, giving you the most room possible to work in. However, if you are working with multiple Compare windows, only one one maximized window is visible: any others are hidden. The screen shot below shows the header area of a maximized Compare window:

To access other Compare windows, you could return to the default view by clicking the Restore button. But a better solution is to enable tabs by setting (checking) View → Tab Bar.

When you display the Tab bar, each Compare window has a tab that shows the filenames of the two compared files. Now, you can easily identify the available Compare windows. To open any of them, just click its tab:

Here are the functions for navigating differences in the File Compare window, and their shortcuts in the toolbar and menus:

By default, the Automatic rescan option is enabled in the Editor page of WinMerge options. Rescanning keeps your your compare and merge operations up to date. Without rescanning, WinMerge differences does not detect changes that might occur to files while you are comparing them, for example in an external editor.

Rescanning occurs when you perform certain actions (like merging a difference or editing a file) during a file compare. If a file has changed, WinMerge displays a dialog advising you that another application has updated the file, and asks whether you want to reload the file.

Click Yes to reload the file before proceeding, or No to ignore the changes and work with the earlier loaded version of the file.

	Important
	If Automatic rescan is disabled, or if you suspect that a file might have changed, we strongly advise that you run Refresh before performing any merge operation: click Edit → Refresh or the toolbar button, or press F5. If a merge result looks incorrect, click Edit → Undo or press Ctrl+Z to undo the merge. Then rescan the files and try merging again.

The merging functions can implicitly select differences based on a cursor location or text selection. For example, if you click anywhere in a difference and then click the Copy Right toolbar button, the entire difference block is merged. This makes it easy to merge many small differences. Similarly, if you select text that spans all or part of multiple differences, all the included differences are merged with a single merge command.

If the result of a merge operation is not what you expected, you can click Undo to reverse the operation.

Here are the merge functions and their shortcuts in the toolbar and menus:

You can use WinMerge to resolve conflict files that some version control systems produce during their merge operations. A conflict file is created when a merge encounters differences that cannot be automatically resolved. It is a single file containing the incompletely merged content of the two files. WinMerge separates the conflict file into separate files and opens those files in file Compare window. You can then use WinMerge's compare and merge functions to resolve the conflicts and save the merged result file.

Many version control systems allow you to configure an external merge tool. If yours does, you might be able to have your version control system launch WinMerge automatically when a merge conflict occurs.

You can also open a conflict file from the WinMerge command line, which accepts three filename parameters: Theirs, Mine, and optionally, Resolved (if you want a different result file from the conflict file). For more information, see Command line. Single path to the conflict file is also accepted in command line.