Plugins


WinMerge plugins are custom dlls or scriptlets, written in the COM API, that preprocess data before a comparison. For example, you can use a plugin to extract text data from MS Word files for WinMerge to compare.

Each plugin is:

1. Plugin Types

Plugins are grouped into three main categories:

Editor complement

This type of plugin performs custom operations on selected text in the active editor (File pane) of the File Compare window.

Unpacker: transform a file to a text format

This type of plugin transforms a compressed file to a viewable format by decompressing it. The original file is not changed: a temporary transformed file is created and loaded in WinMerge.

Unpacker plugins operate on entire files, not to selected text or diffs within files. Therefore, they are available only when you launch file comparisons, from either the Folder Compare window or the Select Files or Folders dialog. Unpacker plugins are not available in the File Compare window.

Sometimes the unpacked file can be repacked (see the details in Available plugins to check whether a plugin supports repacking). Then, you can merge and save the transformed file. The packing is done automatically in this case. To be safe, we suggest that you rename the transformed file when you save it.

Note

When you compare folders, WinMerge can give different results for compressed and uncompressed files. For example, files that are identical when uncompressed might be different if they include the creation date. WinMerge applies the unpacker in all situations, and you are sure to have the same result when you compare a folder, or when you merge two versions of a file.

Example plugin: CompareMSExcelFiles displays the text contents of a Microsoft® Excel file.

Prediffer: preprocess files to hide some differences

This type of plugin does not operate on the source files displayed in the Compare window. It operates instead on temporary copies of the files, and the copies are then scanned to create the difference list.

Example plugin: IgnoreColumns ignores the differences inside specified columns, while displaying the characters in these columns.

2. Suggested plugins and automatic modes

How is WinMerge able to apply the right plugin for a given file? Each plugin specifies a list of file extensions (also listed in each plugin's Available plugins section, under File filter). The extensions are used to associate one or more file types with the plugin: when a compared file's extension matches an extension in the plugin's list, the plugin is considered to be a suggested plugin.

There are separate WinMerge options for the unpacking and prediffer types, described later in this topic, that enable you to apply the plugins either manually or automatically. There is no automatic mode for editor complement plugins.

When you apply plugins to a selected file using automatic mode, WinMerge searches its list of suggested plugins for that file type, and applies the first plugin whose name matches. The search is performed in alphabetical order, so if there are multiple suggested plugins for a file type, only the first one found is applied.

3. Applying plugins

The following subsections describe how to apply each type of plugin. The methods are different for each type of plugin, and also vary depending on whether you are comparing folders or files.

3.1. Applying editor complement plugins in the File Compare window

With your cursor in either File pane of the File Compare window, click PluginsScripts and choose one of these functions:

  • Make Uppercase

  • Make Lowercase

  • Remove Duplicate Lines

  • Count Duplicate Lines

  • Sort Lines Ascending

  • Sort Lines Descending

  • Reverse Columns

  • Reverse Lines

  • Select Columns...

  • Select Lines...

  • Replace...

  • Apply Filter Command...

  • Tokenize...

  • Trim Spaces

  • Insert Date

  • Insert Time

The functions are contributed to the Scripts menu by the editor addin and insert datetime plugins.

Note

Editor complement plugins are not available in the Folder Compare window.

3.2. Applying unpacker plugins in the Folder Compare window

Before applying unpacker plugins, you can set its mode to either automatic or manual mode.

  • To set automatic mode for this type of plugin, click PluginsAutomatic Unpacking.

  • To set manual mode, click PluginsManual Unpacking.

Remember to click F5 to reload the Folder Compare window using the new setting.

3.2.1. Using automatic mode

To apply plugins when automatic unpacking is set, simply launch a compare operation on a file in the Folder Compare window. If the file's type suggested unpacker plugin (if any) preprocesses the file before WinMerge opens it in the File Compare window.

For example, suppose you right-click an MS Word doc file and choose Compare (also assume that the CompareMSWordFiles plugin is available). WinMerge converts the doc file (or rather, a copy of it ) to a plain text file and opens it in the File Compare window.

3.2.2. Using manual mode

Manual mode enables you to choose a different unpacker plugin than the one that is selected for you in automatic mode. You can also launch the compare using no plugin.

To apply plugins when manual unpacking is set:

  1. Select the file you want to compare.

  2. Click PluginsEdit with Unpacker.

    This menu item is enabled only if the selected file's type is supported by an available unpacking plugin.

  3. In the Select Unpacker dialog:

    1. Configure automatic plugin selection or choose a plugin manually:

      • To use automatic mode (which applies the first available plugin), verify that <Automatic> is displayed in the File unpacker control.

      • To choose a different plugin (if available), use the File unpacker control to choose the plugin.

        By default, this control lists only suggested plugins for the file type you selected to compare. To see all available plugins, enable the option, Display all packers, don't check the extension.

      • To launch the compare without using any plugin, choose <None> in the File unpacker control.

    2. Click OK to close the Select Unpacker dialog.

  4. Click OK to close the Select Unpacker dialog and launch the file comparison.

3.3. Applying unpacker plugins in the Select Files or Folders dialog

You can use the Select Unpacker dialog to apply a plugin when you launch a file comparison from the Select Files or Folders dialog. See Selecting an unpacker for file comparisons for details.

3.4. Applying prediffer plugins in the Folder Compare window

With prediffer plugins, you set the mode (<Automatic> or <None>) or the plugin name for individual files. (Contrast this with unpacker plugins, where you set the mode for all files.) That is, some files in the same folder have different prediffer modes.

To set the mode for one or more files in the Folder Compare window, right-click the files and choose Plugin SettingsPrediffer Settings, then choose one of the submenu options:

  • <Automatic> selects the first prediffer plugin available for the file type.

  • <None> means that no prediffer plugin is used.

Click F5 to update the window.

Note

When you open a subfolder during a non-recursive compare, the mode is always reset to <None>.

When you open a file from the Folder Compare window, your prediffer setting for that file is applied before the File Compare window is opened.

3.5. Applying prediffer plugins in the File Compare window

In the File Compare window, you can apply a prediffer plugin by clicking PluginsPrediffer and choosing one of the plugins in the list. Suggested plugins are indicated at the top of the list. The files are compared again after the plugin is applied, so you don't need to rescan the files.

4. Available plugins

4.1. CompareMSExcelFiles

Displays the text contents of a Microsoft® Excel file, stripping away all formatting and embedded objects.

Category: Unpacker
File filter: *.xls, *.xlsx, *.xlsm, *.xlsb, *.xla, *.xlax, *.xltx, *.xltm
Plugin arguments: No
Packing: No
Settings dialog support: Yes
Dependency: Microsoft® Excel

4.2. CompareMSPowerPointFiles

Displays the text content of a Microsoft® PowerPoint file, stripping away all formatting and embedded objects.

Category: Unpacker
File filter: *.ppt, *.pptx, *.pptm, *.ppa, *.ppam, *.pot, *.potx, *.potm
Plugin arguments: No
Packing: No
Settings dialog support: Yes
Dependency: Microsoft® PowerPoint

4.3. CompareMSVisioFiles

Displays the text content of a Microsoft® Visio file, stripping away all formatting and embedded objects.

Category: Unpacker
File filter: *.vsd, *.vsdx, *.vsdm, *.vss, *.vssx, *.vssm, *.vst, *.vstx, *.vstm
Plugin arguments: No
Packing: No
Settings dialog support: Yes
Dependency: Microsoft® Visio

4.4. CompareMSWordFiles

Displays the text content of a Microsoft® Word file, stripping away all formatting and embedded objects.

Category: Unpacker
File filter: *.doc, *.docx, *.docm, *.dot, *.dotx, *.dotm
Plugin arguments: No
Packing: No
Settings dialog support: Yes
Dependency: Microsoft® Word

4.5. PrettifyHTML

HTML Prettier with tidy-html5

PrettifyHTML [arguments...]

arguments

Command line options passed to the tidy command

Category: Unpacker
File filter: *.html, *.htm
Plugin arguments: Yes
Packing: No
Settings dialog support: No
Dependency: tidy-html5

4.6. PrettifyXML

XML Prettier with tidy-html5

PrettifyXML [arguments...]

arguments

Command line options passed to the tidy command

Category: Unpacker
File filter: *.xml
Plugin arguments: Yes
Packing: No
Settings dialog support: No
Dependency: tidy-html5

4.7. PrettifyJSON

JSON Prettier with jq command

PrettifyJSON [arguments...]

arguments

Filter or command line options passed to the jq command

Category: Unpacker
File filter: *.json
Plugin arguments: Yes
Packing: No
Settings dialog support: No
Dependency: jq

4.8. PrettifyYAML

YAML Prettier with yq command

PrettifyYAML [arguments...]

arguments

Filter or command line options passed to the yq command

Category: Unpacker
File filter: *.yaml, *.yml
Plugin arguments: Yes
Packing: No
Settings dialog support: No
Dependency: yq

4.9. QueryCSV

CSV Querier with q command

QueryCSV [arguments...]

arguments

SQL statement or command line options passed to the q command

Category: Unpacker
File filter: *.csv
Plugin arguments: Yes
Packing: No
Settings dialog support: No
Dependency: q

4.10. QueryTSV

TSV Querier with q command

QueryTSV [arguments...]

arguments

SQL statement or command line options passed to the q command

Category: Unpacker
File filter: *.tsv
Plugin arguments: Yes
Packing: No
Settings dialog support: No
Dependency: q

4.11. QueryJSON

JSON Querier with jq command

QueryJSON [arguments...]

arguments

Filter or command line options passed to the jq command

Category: Unpacker
File filter: *.json
Plugin arguments: Yes
Packing: No
Settings dialog support: No
Dependency: jq

4.12. QueryYAML

YAML Querier with yq command

QueryJSON [arguments...]

arguments

Filter or command line options passed to the yq command

Category: Unpacker
File filter: *.yaml, *.yml
Plugin arguments: Yes
Packing: No
Settings dialog support: No
Dependency: yq

4.13. ValidateHTML

HTML Validator with tidy-html5

ValidateHTML [arguments...]

arguments

Command line options passed to the tidy command

Category: Unpacker
File filter: *.html, *.htm
Plugin arguments: Yes
Packing: No
Settings dialog support: No
Dependency: tidy-html5

4.14. VisualizeGraphviz

Graphviz Visualizer

VisualizeGraphviz [arguments...]

arguments

Command line options passed to the dot command

Category: Unpacker
File filter: *.gv, ,*.dot
Plugin arguments: Yes
Packing: No
Settings dialog support: No
Dependency: Graphviz

4.15. ApacheTika

General content extractor with Apache Tika

ApacheTika [arguments...]

arguments

Command line options passed to the tika-app.jar

Category: Unpacker
File filter: *.*
Plugin arguments: Yes
Packing: No
Settings dialog support: No
Dependency: Java, Apache Tika

4.16. DisassembleJVM

JVM bytecode disassembler with javap

DisassembleJVM [arguments...]

arguments

Command line options passed to the javap command

Category: Unpacker
File filter: *.class
Plugin arguments: Yes
Packing: No
Settings dialog support: No
Dependency: Java

4.17. DisassembleIL

IL code disassembler with ildasm

DisassembleIL [arguments...]

arguments

Command line options passed to the ildasm command

Category: Unpacker
File filter: *.obj, *.lib, *.exe, *.dll
Plugin arguments: Yes
Packing: No
Settings dialog support: No
Dependency: Visual Studio

4.18. DisassembleNative

Native code disassembler with dumpbin

DisassembleNative [arguments...]

arguments

Command line options passed to the dumpbin command

Category: Unpacker
File filter: *.obj, *.lib, *.exe, *.dll
Plugin arguments: Yes
Packing: No
Settings dialog support: No
Dependency: Visual Studio

4.19. ExecFilterCommand

Applys filter command

ExecFilterCommand [command]

command

command to execute. %1 in the command is replaced with the filename

Category: Unpacker
File filter: *.nomatch
Plugin arguments: Yes
Packing: No
Settings dialog support: No
Dependency: Windows Script Host

4.20. MakeUpper

Makes characters uppercase

Category: Unpacker
File filter: *.nomatch
Plugin arguments: No
Packing: No
Settings dialog support: No
Dependency: Windows Script Host

4.21. MakeLower

Makes characters lowercase

Category: Unpacker
File filter: *.nomatch
Plugin arguments: No
Packing: No
Settings dialog support: No
Dependency: Windows Script Host

4.22. RemoveDuplicates

Removes duplicate lines

Category: Unpacker
File filter: *.nomatch
Plugin arguments: No
Packing: No
Settings dialog support: No
Dependency: Windows Script Host

4.23. CountDuplicates

Counts duplicate lines

Category: Unpacker
File filter: *.nomatch
Plugin arguments: No
Packing: No
Settings dialog support: No
Dependency: Windows Script Host

4.24. SortAscending

Sorts lines ascending

Category: Unpacker
File filter: *.nomatch
Plugin arguments: No
Packing: No
Settings dialog support: No
Dependency: Windows Script Host

4.25. SortDescending

Sorts lines descending

Category: Unpacker
File filter: *.nomatch
Plugin arguments: No
Packing: No
Settings dialog support: No
Dependency: Windows Script Host

4.26. ReverseColumns

Reverses columns

Category: Unpacker
File filter: *.nomatch
Plugin arguments: No
Packing: No
Settings dialog support: No
Dependency: Windows Script Host

4.27. ReverseLines

Reverses lines

Category: Unpacker
File filter: *.nomatch
Plugin arguments: No
Packing: No
Settings dialog support: No
Dependency: Windows Script Host

4.28. SelectColumns

Selects some columns

SelectColumns [ranges]

SelectColumns [-v] [-i] [-g] [-e patterns]

ranges

list of column ranges to select. (e.g. -3,5-10,30-)

patterns

regular expression

-v

select non-matching columns

-i

ignore case

-g

enable global flag

-e

use patterns for matching

Category: Unpacker
File filter: *.nomatch
Plugin arguments: Yes
Packing: No
Settings dialog support: No
Dependency: Windows Script Host

4.29. SelectLines

Selects some lines

SelectLines [ranges]

SelectLines [-v] [-i] [-e patterns]

ranges

list of line ranges to select. (e.g. -3,5-10,30-)

patterns

regular expression

-v

select non-matching columns

-i

ignore case

-e

use patterns for matching

Category: Unpacker
File filter: *.nomatch
Plugin arguments: Yes
Packing: No
Settings dialog support: No
Dependency: Windows Script Host

4.30. Replace

Replaces text with another text

Replace [-i] [-e] [text_to_find] [text_to_replace]

text_to_find

text to find

text_to_replace

text to replace

-i

ignore case (only for -e)

-e

treat the specified text as a regular expression

Category: Unpacker
File filter: *.nomatch
Plugin arguments: Yes
Packing: No
Settings dialog support: No
Dependency: Windows Script Host

4.31. Tokenize

Tokenizes selection

Tokenize [patterns]

patterns

regular expression for tokenizing. (e.g. [^\w]+)

Category: Unpacker
File filter: *.nomatch
Plugin arguments: Yes
Packing: No
Settings dialog support: No
Dependency: Windows Script Host

4.32. Trim

Trim spaces

Category: Unpacker
File filter: *.nomatch
Plugin arguments: No
Packing: No
Settings dialog support: No
Dependency: Windows Script Host

4.33. IgnoreColumns

This plugin ignores characters at specified columns. The first column is number 1.

Note that this plugin does not support files with tabs: the plugin does not fail, but all tabs are be treated as normal characters.

To specify columns, use plugin settings dialog or rename the dll using following fields as parameters:

  • Delimiters between ranges: _ or ,
  • Delimiters between min and max: anything else
  • Min and max are included.
  • When max = min, max can be omitted.

Example 1. IgnoreColumns examples

IgnoreColumns _ 3 _ 10 - 20 _ 32 - 33.dll
Ignore all characters at column 3, and in columns 10 to 20, and 32 to 33.
IgnoreColumns_1,30 to 40.dll
Ignore all the characters in column 1, and in columns 30 to 40.

Category: Prediffer
File filter: *.txt
Plugin arguments: Yes

4.34. IgnoreCommentsC

The plugin ignores comments within //... and /* ... */ delimiters in C, C++, PHP and JavaScript files.

Category: Prediffer
File filter: *.cpp, *.cxx, *.h, *.hxx, *.c, *.php, *.js, *.cs, *.ts
Plugin arguments: No
Settings dialog support: No

4.35. IgnoreFieldsComma

This plugin is for files with fields and commas as delimiters (CSV files, for example). It ignores the delimiter characters. The first field is number 1.

To specify the delimiters, use plugin settings dialog or rename the dll using the same parameter fields used for IgnoreColumns.

Category: Prediffer
File filter: *.csv
Plugin arguments: Yes
Settings dialog support: Yes

4.36. IgnoreFieldsTab

This plugin is for files that use fields and tabs as delimiters (for example, Excel files saved in the *.txt format). It ignores the delimiter characters. The first field is number 1.

To specify the delimiters, use plugin settings dialog or rename the dll using the same parameter fields used for IgnoreColumns.

Category: Prediffer
File filter: *.txt
Plugin arguments: Yes
Settings dialog support: Yes

4.37. IgnoreLeadingLineNumbers

This plugin ignores the leading line numbers in text files (for example, NC and BASIC files).

Category: Prediffer
File filter: *.nc
Plugin arguments: No
Settings dialog support: No

4.38. editor addin

Adds some functions to the PluginsScripts menu:

  • Make Uppercase convert the selection to UPPER CASE.
  • Make Lowercase convert the selection to lower case.
  • Remove Duplicate Lines remove duplicate lines in the selection.
  • Count Duplicate Lines remove duplicate lines in the selection and insert the number of duplicate lines on the right.
  • Sort Lines Ascending sort the selection in ascending order.
  • Sort Lines Descending sort the selection in descending order.
  • Reverse Columns reverse columns in the selection.
  • Reverse Lines reverse lines in the selection.
  • Select Columns... select some columns in the selection.
  • Select Lines... select some lines in the selection.
  • Replace... replace text in the selection with another text.
  • Apply Filter Command... replace the selection with the output of the specified filter command. Specifying %1 in the argument of the filter command replaces it with the filename of the active pane.
  • Tokenize... replaces the token delimiter with a newline in the selection.
  • Trim Spaces remove spaces at the beginning and end of lines in the selection.
Category: Editor complement
File filter: *
Settings dialog support: No

4.39. insert datetime

Adds two functions to the PluginsScripts menu:

  • Insert Date insert date in the current locale format.
  • Insert Time insert time in the current locale format.
Category: Editor complement
File filter: *
Settings dialog support: No

5. Requirements

5.1. Windows Script Host

Some editor complement plugins require this optional component from Microsoft®.

It should already be included in your version of Windows, unless you use some really old pre Windows XP version.

5.2. Visual Basic runtime library

Some plugins require the Visual Basic runtime library to work.

You can use the Run-Time Redistribution Pack from Microsoft®. If you don't need the plugin, you can safely remove it.