Options and configuration

WinMerge

Options and configuration


The Options dialog enables you to customize many WinMerge features. To set WinMerge options:

  1. Click EditOptions in the menu or the WinMerge Options button Options button in the toolbar.

    The Options dialog contains a number of pages, each containing a group of related options. You can open any page by clicking its title in the Categories list, on the left side of the dialog.

  2. Configure the options you want to change using one or both of these methods:

  3. When you have set all your options, click OK to save them and dismiss the dialog.

This topic describes the options in detail. There is a section for each page in the Options dialog.

1. Importing and Exporting options

If you change options frequently for different compare or merge scenarios, or if you want to share your settings with other WinMerge users, consider saving your settings by exporting them to an options file. Then, whenever you want to use those settings, you can simply import the options file instead of setting options manually.

To export options

When you have set your options the way you want them, click Export. In the Select file for export dialog, specify a path and name for your options file (the type ini is automatically appended), and click Save.

In the generated text ini file, each line contains a name-value pair that defines a single option.

To import options

When you want to reuse your saved options, click Import. In the Select file for import dialog, navigate to the saved ini file and click Open.

The values in your imported options file replace all existing settings.

2. General page

The General page has these options:

2.1. Automatically scroll to first difference

  • Disabled (default): Compare window opens to the top of the folder or file, with no difference selected.

  • Enabled: When it first opens, the Compare window selects the first difference, scrolling to the location if necessary.

    • For a folder compare, selects the first different file or folders.

    • For a file compare, selects the first difference block in the files.

2.2. Disable splash screen

  • Disabled (default): A splash screen is displayed when you start WinMerge. You can dismiss the screen at any time by clicking it; otherwise it is automatically dismissed after a few seconds.

  • Enabled: Completely omits the splash screen when you start WinMerge. Note that this does not make startup faster.

2.3. Close Windows with ESC

  • Enabled (default): Lets you use the ESC key to close WinMerge windows. Pressing ESC once closes one window, so with one File Compare window open, it takes three key presses to close WinMerge: first the File Compare window, then the Folder Compare window, and finally the WinMerge window.

    Note that in the WinMerge command line, the -e parameter enables you to close WinMerge by pressing ESC just once.

  • Disabled: Pressing ESC does not close any WinMerge windows.

2.4. Automatically verify paths in Open-dialog

  • Enabled (default): The Select Files or Folders dialog checks both paths as you enter them. The OK button remains disabled until both paths are validated. Note that this checking can cause some delay.

  • Disabled: The OK button in the Select Files or Folders dialog is always enabled, and attempts to open any paths you specify. Since there is no delay during validation, this can speed up the selection of paths. However, if the path cannot be opened, an error dialog is displayed.

2.5. Allow only one instance to run

  • Disabled (default): You can run multiple WinMerge instances. For example, if WinMerge is currently running and you click the WinMerge desktop shortcut, a new WinMerge window is opened.

  • Enabled: Limits the WinMerge program to one instance:

    • If WinMerge is currently running and you try to start a new instance, no new application window is opened: the current WinMerge window is used instead.

    • If you start a new instance with paths (for example on the command line), a new Compare window is opened in the existing WinMerge window.

Also see the related options under Enable multiple compare windows for.

2.6. Ask when closing multiple windows

  • Disabled (default): If you exit WinMerge while multiple Compare windows are open, WinMerge prompts you to confirm whether to close all the windows.

  • Enabled: If you click Exit and there are no pending file changes, WinMerge closes immediately.

2.7. Preserve file time in file compare

  • Disabled (default): If you save changes to a file in WinMerge, the timestamp of the file is updated.

  • Enabled: If you save changes to a file in WinMerge, the timestamp of the file is not changed in your file system.

2.8. Show "Select Files or Folders" Dialog on Startup

  • Disabled (default): The WinMerge window opens when you launch WinMerge. You must then click FileOpen to open Select Files or Folders.

  • Enabled: The Select Files or Folders dialog opens along with the WinMerge window when you launch WinMerge.

2.9. Open-dialog Auto-Completion

Choose one of these options:

  • Disabled (default): No autocompletion is performed when you enter paths in the Select Files or Folders dialog.

  • From file system: Checks paths as you type. It attempts to locate paths in the file system that match the letters you type, and if a matching path is found, completes the path.

  • From MRU list: Checks paths only from the most recently used (MRU) list. This is handy when you have a limited set of paths to compare.

2.10. Enable multiple compare windows for

Controls whether WinMerge allows you to open single or multiple Compare windows. Specify the Folder compare and File compare options independently:

  • Disabled (default): You can only open one Folder compare or File compare window at a time.

  • Enabled: You can open multiple Folder or File compare windows simultaneously.

    [Note] Note

    File Compare windows are children of Folder Compare windows. Therefore, you can open one File Compare window for every Folder Compare window, even if the File compare option is disabled.

2.11. Reset

WinMerge allows you to suppress some common message boxes. For example, when two identical files are opened, the message box titled, The files are identical, is normally opened. If you don't want this box to display any more, you can enable (check) the option in that message box to not show the message again.

Later, you might decide that you want to see those messages again. If so, click the Reset button to make the message boxes display again.

[Note] Note

We recommend that you not suppress messages when updating WinMerge to a newer version. The installer enables their display automatically, but if you don't use the installer, then remember to enable message display by using the Reset button.

3. Compare General page

The options in this page enable you to change some of the ways that WinMerge detects differences, such as comparing only file size, or ignoring some types of differences, like case.

[Important] Important

Customizing difference detection can be useful during comparisons, when you might not be interested in some differences. However, these options also affect merging. For example, if you ignore whitespace changes, then indentation changes in source code files are not preserved when you merge.

For this reason, before you merge any differences, we strongly recommend resetting the options on this page to their default settings, especially the ignore options. To reset all the options on this page, click the Defaults button.

3.1. About ignore options

A number of options in the Compare page (described later in this section) enable you to ignore certain differences. Ignored differences are treated in special ways in WinMerge:

  • They are marked with the Ignored Difference color.

  • Ignored differences cannot be merged

  • Ignored differences are not included in difference counts

  • Files containing only ignored differences are marked as identical in a folder comparison

3.2. Whitespace

Whitespace is the space between words and lines. It is represented in text files by special, nonprinting characters like spaces, tabs, and linefeeds. The significance of whitespace depends on how you want to read or process differences. It might be important to detect all changes in whitespace. Conversely, you might prefer to treat all whitespace the same whether one space, two spaces, an indent, or a tab. And in some structured documents (like comma-separated lists), you might want to disregard all whitespace.

[Note] Note

The effects of whitespace on changes within lines are visible only when View line differences is enabled. This is in contrast to difference blocks, which are always highlighted.

Example 1. Lines with different whitespace

One space between words:

Two Words

Two spaces between words:

Two  Words

Tab between words:

Two	Words

No spaces between words:

TwoWords

You can control whitespace detection by choosing one of these options:

Compare

All whitespace is compared (default). If you are not sure which option your document requires, this is probably the safest choice. In the example, all lines are detected as different.

Ignore change

Compares differences in whitespace. In the example, the first three lines have different whitespace, but are detected as identical: tabs and multiple are treated as if they are single space. The last line has no whitespace, so the difference is not ignored (in effect, the words in the last two lines are different):

Ignore all

Ignores all whitespace characters, except linefeeds (so lines are detected and preserved in a merge). All lines in the example are detected as identical.

[Note] Related topics

The effects of whitespace settings on line differences is described in Line difference highlighting.

The Options dialog Editor page contains related options that control how whitespace is used to detect breaks between words. See View line differences for details.

3.3. Ignore blank lines

  • Disabled (default): Empty lines in the source files are detected and represented in the File Compare window as blank lines with the Deleted Difference colors.

  • Enabled: Empty lines in the source files are ignored. They are represented in the File Compare window as blank lines with the Ignored Difference colors. However the difference cannot be merged.

3.4. Ignore case

  • Disabled (default): Comparisons are case-sensitive. For example, LowerCase, LOWERCASE, and lowercase are all different.

  • Enabled: Differences between lowercase and uppercase letters are ignored.

3.5. Ignore carriage return differences (Windows/Unix/Mac)

  • Disabled (default): End of line (EOL) style differences are detected. For example, if you compare two lines that have the same contents but different line endings, the lines are considered to be different. When this happens, WinMerge displays a dialog prompting you to confirm whether to detect or ignore the difference.

  • Enabled: EOL differences are ignored.

3.6. Enable moved block detection

  • Disabled (default): WinMerge does not detect when differences are due to moved lines.

  • Enabled: WinMerge tries to detect lines that are moved (in different locations in each file). Moved blocks are indicated by the Moved and Selected Moved difference colors. If the Location bar is displayed, corresponding difference locations in the left and right location bars are connected with a line. Showing moved blocks can make it easier to visualize changes in files, if there are not too many.

    For an example, see the Location pane description in Comparing and merging text files.

3.7. Match similar lines

  • Disabled (default): Lines within difference blocks are shown as they occur in the source files.

  • Enabled: WinMerge tries to detect lines within a difference blocks that are similar, and adds blank lines in the File panes to align them. This option is most effective when lines are quite similar; less effective if lines are too different.

    For an example, see the Similar lines description in Difference highlighting.

3.8. Filter Comments

  • Disabled (default): WinMerge compares comments in code, along with other content.

  • Enabled: This option optimizes comparisons by detecting comments in certain programming language file types (such as C++ and Java), and ignoring them.

    The recognized file types and their comment markers are defined in the file, IgnoreSectionMarkers.ini, at the top of the WinMerge installation directory.

4. Compare Folder page

4.1. File Compare method

This option lets you determine how complete your file comparisons are. Choose one of these five choices:

Full Contents

Default: Full comparison of files by content, with all the bells and whistles. This method invokes plugins and uses the diffutils engine for fully accurate differencing and moved block detection. This is the most complete and recommended method.

Quick Contents

Slimmed-down comparison of files by content. This method uses streamlined file comparison code which skips plugins and moved block detection. This method is faster than Full Contents, because it does not load the files.

Its drawback is that line filters are not applied when comparing. For example, this method sees file as different even if line filters are set to ignore all differences in the files.

Modified Date

Compares only the modification dates on the files, so it is far faster than either of the contents methods. But obviously, it is only as accurate as the modification dates.

Modified Date and Size

Similar to Modified Date, but also checks file sizes when dates are identical.

Size

Compares only file sizes, so it is fast but not as accurate as the contents methods.

4.2. Stop after first difference

This option is enabled only when the Quick Contents compare method is selected.

  • Disabled (default): WinMerge examines all differences in the files.

  • Enabled: This option optimizes comparisons by examining files only until the first difference is found, instead always scanning the entire files.

    The drawback is that WinMerge may be unable to identify binary files as binary. This is likely to happen if the first difference is near the beginning of the file. If you know what kind of files you are comparing (for example, which are binary files), this option can be a good way to speed up comparisons. However, don't enable this option if you are not sure what kind of files you are comparing.

4.3. Ignore time differences less than 3 seconds

  • Disabled (default): Files with different timestamps are detected as different.

  • Enabled: Sometimes (for example, when you use network shares) small differences in timestamps are not significant. To get more meaningful results in such situations, this option enables you to ignore time differences smaller than three seconds.

    This option works only with the Modified Date and Modified Date and Size compare methods (described in File Compare method). It has no effect with other methods.

    [Warning] Warning

    This option should be enabled only when the time difference is detected. Otherwise, it can cause incorrect compare results.

4.4. Quick compare limit (MB)

  • Disabled: Is not active unless the Compare method is set to Quick Contents.

  • Enabled: Is active when the Compare method is set to Quick Contents.

    This option sets the limit when WinMerge should stop comparing. If the limit is set to for instance 4 MB, then WinMerge will only read the first 4 MB of a file. If no differences are founf before the Quick Compare limit is reached, then the files will be marked as identical.

    [Warning] Warning

    This option should be enabled only when you are sure any differences are in the first part of the file. Otherwise, it can cause incorrect compare results.

5. Editor page

5.1. Syntax highlighting

  • Enabled (default): WinMerge can syntax highlight many programming language and web formats. To see the formats that are supported by default, click ViewSyntax Highlight.

  • Disabled: Syntax highlighting consumes some processing power, so if WinMerge screen updating seems to be slow, turning off this option might help.

5.2. Automatic rescan

  • Disabled (default): WinMerge rescans automatically when you merge a difference, or if you manually rescan (for example, click the Rescan button).

  • Enabled: Forces WinMerge to rescan after every edit event (a change to files, like typing).

    [Note] Note

    To avoid slowing down your editing, WinMerge delays automatic rescanning a little: it waits one second after each edit event. Because each new edit event resets the timer, no rescans occur until you pause or stop editing.

5.3. Preserve original EOL chars

  • Disabled (default): Assumes that files are meant to be Windows files. If a file does not use the standard Windows line ending, WinMerge considers this to be an error. It silently changes the line endings to the Windows style instead of detecting them as differences. Thus, the File Compare window status bar shows the EOL style as Win.

    For most situations you should leave this option disabled: the default behavior works even when comparing two files that have different line ending styles.

  • Enabled: Prevents WinMerge from automatically changing line endings, so that it detects different EOL styles for every line. This might be useful for handling files from systems with different EOL styles (for example, Windows and Unix).

    [Important] Important

    This is an advanced option for users who are familiar with EOL bytes and who want to compare files with different EOL styles inside one file. We recommend that you not enable this option unless you need this advanced functionality. Remember, this option is not required to compare two files with different EOL styles.

5.4. Tab options

Tab size

Width of a tab space. Specify a value n : the resulting width is equivalent to that of n characters. Default: 4. The maximum value is 64.

Tab insert options

Determines what kind of character is used when you insert a tab in text. Only one of these options can be enabled:

  • Insert Tabs (default): Uses a single tab character.

  • Insert Spaces: Uses one or more spaces (determined by the Tab size) instead of a tab character. For example, with the default tab size, four spaces are inserted.

5.5. View line differences

These settings enable and configure the detection of line differences (changes within the lines of difference blocks):

  • Enabled (default): WinMerge highlights differences within lines. Also enables the ViewView Line Differences menu item.

    Choose one of these suboptions:

    • Character level: Highlights individual characters that are different. This option can be useful if you are looking for changes within words, or for file formats that do not have clear word breaks.

    • simiWord-level (default): Highlights entire words that are different.

      • Break at whitespace (default): Words are assumed to be separated by whitespace characters. This usually works for typical text files.

      • Break at whitespace or punctuation: Considers both whitespace and punctuation characters to be word breaks. This can useful for handling lists that are separated with punctuation (like comma-separated lists).

  • Disabled: WinMerge does not highlight line differences, and all settings for the level and whitespace options are ignored. Also disables the ViewView Line Differences menu item.

[Note] Related topic

Line difference highlighting explains in more detail how WinMerge detects and marks line differences.

6. Colors page

Use this page if you want to change any of the difference colors used in the File Compare window. You can set the background, deleted, and text color.

To change a color, click in its box to open a standard Color chooser dialog. Choose one of the predefined colors or define your own custom color, then click OK to load the new color in the box.

At any time, you can click Defaults to reload the installed color scheme.

7. Text Colors page

Use this page to change the colors used for text. First, check the option, Use customized text colors. This activates the text options. There is an option for three kinds of text: whitespace, regular text, and selected text. For each kind of text , you can choose a color for the background and the text.

8. Syntax Colors page

By default, the WinMerge File Compare window marks the syntax of certain kinds of source code, as described in Syntax highlighting. This page lists the syntax elements that are recognized, and enables you to change their text color and weight.

At any time, you can click Defaults to reload the installed color scheme.

9. Archive Support page

This page contains options for configuring Winzip archive support using 7-Zip.

9.1. Download 7-zip Plugin

If WinZip is already installed on your system, WinMerge automatically detects it, and you don't need to configure anything here. Otherwise, you can click this link to open the WinMerge downloads page in your Web browser. There, you can download the 7-Zip Plugin installer (and other WinMerge files). To install the plugin, see 7-Zip and archive support. Remember to close WinMerge before running the 7-Zip installer.

9.2. Enable archive file support

This option controls how WinMerge handles archive files (based on 7-Zip integration).

  • Enabled (default): WinMerge recognizes 7-Zip archives.

    WinMerge can access 7-Zip from two installation sources. If you specified one of these methods earlier (for example, during the WinMerge installation), you can change it here:

    • Use stand-alone 7-Zip if available

    • Use local 7-Zip from WinMerge folder

  • Disabled: Turns off 7-Zip archive integration.

9.3. Detect archive type from file signature

  • Disabled (default): WinMerge recognizes only archives whose file extension is known on your system (for example, in the registry or through a file association).

  • Enabled: WinMerge can recognize archive files even if their file extension is not known. To recognize an archive, WinMerge searches the beginning of the file for the archive signature bytes.

    [Tip] Tip

    You can use this option to enable WinMerge to recognize Open Office files.

10. System page

10.1. Send deleted files to Recycle Bin

  • Enabled (default): Files and folders that you delete in a Folder Compare window are moved to the Recycle Bin, if it is available.

    [Important] Important

    Remember: if the Recycle Bin on your system has been deactivated, this option does not work, and deleted files are lost!

  • Disabled: Files and folders deleted in a directory compare actually deleted.

10.2. External editor

The WinMerge File Compare window provides common editing functions. If you prefer using your favorite, full-featured editor, you can configure WinMerge to open an external editor from the Folder Compare context menu.

Installation configures Notepad as the default external editor, because it is found on all Windows systems. To configure a different external editor, enter the full path to its executable file.

[Tip] Tip

Along with the path, you can include any command line parameters supported by the external tool, in this format: path to executable -option1 -option2 ...

To use the configured external editor, right-click a file in the Folder Compare window and choose Open Leftwith External Editor or Open Rightwith External Editor.

10.3. Filter Folder

Use this field to specify your own private folder for file filters. By default this folder is your user profile directory (for example, My Documents on Windows XP, or Documents on Windows Vista). When you create a file filter, it is automatically added to this folder.

10.4. Temporary files folder

Specify the folder where WinMerge stores temporary files. Either one of these options is available:

  • System's temp folder (default): For example, this might be C:\Windows\Temp on your system.

  • Custom folder: Click Browse and select a different folder where you have write access.

11. Backup Files page

This page allows you to control how WinMerge creates backup files.

11.1. Create backup files in

Specify when WinMerge should create backup files. You can enable or disable each of these options independently:

  • Folder compare (disabled by default): Backup files are create whenever files are overwritten (copied).

  • File compare (enabled by default): Backup files are created whenever files are saved.

11.2. Create backup files into

Specify where backup files are created. Only one of these options can be enabled:

  • Original file's folder (enabled by default): Backup files are created in the same folder as the source file. This is usually a good choice. The down side is that cleaning up backup files in big folders can take a lot of work.

  • Global backup folder (disabled by default): All backup files are created in one global folder. This makes them easy to clean up. But, if there are multiple source files with same file name, then the most recent backup file overwrites the previous one of the same name.

11.3. Backup filename

When WinMerge creates a backup file, it appends an extension to the source file name. You can choose either or both of these extension schemes:

  • Append .bak -extension (enabled by default): For example, the file.txt is backed up to file.txt.bak.

  • File compare (enabled by default): Timestamps are almost always unique, so this option usually avoids duplicating backup file names when the source files have the same names.

    Also, storing a copy of a file each time you save it provides a way to track changes to the file. However, you should consider that this option can create a lot of files.

12. Version Control page

Use this page to enable or disable checkouts through an installed version control system (VCS) that you select here. If you enable this integration with one of the supported systems, WinMerge opens the checkout dialog for that VCS when you save a versioned file in WinMerge.

  • None (default): When you save a file in WinMerge, there are no interactions with any version control system.

  • Visual SourceSafe (less than 5.0)

    Also enter the path to SS.EXE.

  • Visual SourceSafe (5.0 and above)

  • Rational ClearCase

    Also enter the path to cleartool.exe.

See Using WinMerge with version control systems for details about using this feature.

13. Codepage page

WinMerge detects handles file encoding transparently, and in most cases you should not need to change the default settings.This page allows you to specify the codepages of certain file formats, should you need to.

[Note] Note

A full explanation of text encoding and Windows codepages is beyond the scope of WinMerge documentation. Fortunately, there is lots of information about them on the Internet. For example, here are some places to start:

13.1. Default codepage for non-Unicode files

Choose one of these radio buttons to set the default codepage that WinMerge uses when handling ANSI files:

  • System codepage (default):The codepage used by your Windows system. This default is usually the best choice. However if you know that you are comparing files that do not use the system codepage, consider one of the other options.

  • According to WinMerge User Interface: The encoding used by your installation of WinMerge.

  • Custom codepage: Enter the codepage number explicitly. For example, UTF-8 or ISO-8851-1.

13.2. Detect codepage info for these files: .html .rc .xml

[Important] Important

Uncheck this option in WinMerge.exe. Characters conversions can result in lossy conversions and the risk is very high. WinMerge.exe can display files only with your current codepage.

  • Disabled (default): WinMerge does not read codepage information from the source files. It uses the default codepage setting instead.

  • Enabled: WinMerge detects the codepage for these extensions : html, rc (resource files for VC++) and xml. The detected codepage overrides the setting for the default codepage option.

    This option is of interest when your documents use a codepage that is different from the codepage of your Windows configuration.

    For example, you might merge two Slovak or two Japanese files in an English environment. With this option enabled (and with the required fonts), your Slovak, or Japanese, the files are displayed using Slovak, or Japanese, characters.

    WinMerge also detects a codepage difference between the left/right files. To avoid lossy conversions when you merge, copy, or paste, we suggest that you ignore the codepage information.

    [Caution] Caution

    When you copy or paste text to an external application, the external application must use the same codepage as WinMerge does. Refer to the documentation for your external editor. For copying to WinMerge, Internet Explorer offers codepage selection. If your external editor does not support custom codepages, disable this option.

14. Shell Integration page

14.1. Explorer

The Add to context menu option enables you to launch WinMerge directly from Windows Explorer, comparing items that you have selected there. It is enabled or disabled by default during WinMerge installation. If enabled, you can also enable one or both of these options:

Enable advanced menu
  • Disabled (default): Only the WinMerge shortcut is included in the Windows Explorer context menu.

  • Enabled: Replaces the WinMerge shortcut in the Explorer context menu with Compare shortcuts.

Include subfolders by default
  • Disabled (default): folder compare operations are non-recursive.

  • Enabled: The selection includes subfolders, making the compare operation recursive.

[Note] Note

This option does not change the Include Subfolders setting for the Select Files or Folders dialog.

Launching WinMerge operations in Windows Explorer describes how to use the WinMerge and Compare shortcuts.

14.2. Folder compare

The Add Shell menu to context menu option enables you to launch some Windows shell commands from the WinMerge window:

  • Disabled (default). No shell menus are available in the Folder Compare context menu.

  • Enabled: Adds a Left shell menu or Right shell menu, or both, to the Folder Compare context menu. The shell menu (if added) is identical to the path's context menu in Windows Explorer, and enables you to launch its commands in the same way.

    If you right-click an item that occurs on both sides, both the left and right shell menus are available; if the item occurs only on one side, only that side's shell menu appears.

    [Note] Note

    Using the shell menu is just like launching Windows commands outside of WinMerge. Consequently, WinMerge might not respond to some operations in the same way as operations performed inside WinMerge.

    Using Windows shell commands from the Folder Compare window has more information about using the shell menus.