When you compare files or folders, you can use filters to narrow the scope of the comparison. This can be useful when you want to simplify the comparison result by eliminating differences that you are not interested in. Filters are rules based on regular expressions. WinMerge uses the popular PCRE (Perl Compatible Regular Expressions) regular expression engine.
The basic function of filtering is simple: evaluate each item that would normally be compared (a folder, file, or line within a file), and if the filter expression matches the target item, apply the filter. Depending on the type of filter, the item is either included or excluded in the comparison.
There are different WinMerge filters for folder compare and file compare operations:
You can use one or more file masks that specify file extensions to include in a folder comparison. All other files are omitted from your selection.
Define and apply a file mask at the time you launch your folder compare operation:
If you are using the Select Files or Folders dialog, after choosing the Left and Right folders, enter one or more file masks in the Filter field. The masks are applied when you start the folder compare operation.
If you are using the WinMerge command line, use the
-fflag to specify file masks (see the example in the next section).
Remember, you cannot specify both a file mask and a file filter in the field or command line.
Use this syntax for file masks:
Valid delimiters are spaces, commas, colons or semicolons.
A mask with no extension (
*. ) selects files
without any extension, such as
File filters are text files with an extension
flt. They enable you to apply multiple filtering
rules to a folder comparison. Unlike file masks, file filters can either
include or exclude matches.
WinMerge installs a number of predefined file filters. If
these file filters do not provide the filtering you need, you can create
your own. To make that task easier, WinMerge also provides a template file
FileFilter.tmpl. This section describes how to
apply file filters to comparisons, and documents the file filter syntax.
Using the Filters dialog describes how to add, edit, and manage
WinMerge automatically detects file filters in these locations:
- Filters subfolder in the WinMerge installation folder
- Default private filter folder
Before you can apply file filters that exist in any other folder, you must first install them.
You can apply a file filter using any of these methods:
When you launch a folder compare from the Select Files or Folders dialog:
After choosing the Left and Right folders, click Select next to the Filter field.
In the Filters dialog, use the Filefilters tab to choose a file filter and load it in the Filter field.
If a file filter is currently enabled, the selected file filter is already loaded in the Filter field.
Proceed with the compare operation. The file in the Filter field is applied when you start the operation.
To change file filtering after you have already launched a folder compare operation (for example, applying a different filter or disabling filtering):
Click Tools → Filters.
In the Filters dialog, configure your new file filter setting, and click OK.
The new filtering is not automatically applied when you close the Filters dialog: press F5 to see the new results in the Folder Compare window.
When you launch a folder compare from the WinMerge command line, use the
-fflag to specify a file filter.
Remember, you cannot apply both a file mask and a file filter in the field or command line.
This section describes the syntax of WinMerge file filters and provides guidelines for writing them.
The comment delimiter is
##. After a comment delimiter,
all characters in a line are ignored. WinMerge ignores most whitespace
characters in rules. However, a comment must always be preceded by one or
more whitespace (space or tab) characters. To use
characters in a rule, omit the whitespace prefix.
The first two required lines of a file filter are:
Next, your file should contain one or more filter rules. You can add as many rules as you like. There must be one rule per line, and each rule must be entirely on one line (no line breaks are allowed in a rule). Each rule consists of either an f: or a d: type designator, followed by a reqular expression, where:
Among the many regexp special characters, the following are particularly important in file filter rules:
- ^ (beginning of line)
- $ (end of line)
- \ (escape)
No special characters or wildcards are used to match file names. To match all filenames of a certain type, simply omit the filename.
Rules are case-insensitive. For example,
Example 2. File filter rule examples
Some simple file filter rules:
f: \.cpp$ ## Match
*.cppfiles f: \.h$ ## Match
*.hfiles f: ^My ## Match
My*.*files f: Dlg\. ## Match
*Dlg.*files d: \\test$ ## Match
testfolders d: ^\\Build$ ## Match
Buildfolders d: Temp$ ## Match
*Tempfolders (for example,
FirstTemp) d: Src ## Match
Some rules with more complex regular expressions:
f: ^\.#.*$ ##
.#filename.versionfiles f: Dlg\.c(pp)?$ ##
*Dlg.cppfiles f: ^I.*\.h$ ##
I*.hfiles f: Srv[1-9]\.def$ ##
*Srv9.deffiles f: ^[h,k,m] ##
In a file comparison, you can use line filters to ignore single lines. For example, you might use line filters to ignore comments or certain type of generated code, like version control system timestamps. Each line filter is a rule, and you can apply any number of line filters to a file comparison.
To learn how to add, edit, and manage filters, see Using the Filters dialog.
You can apply line filters using any of these methods:
When you launch a file compare from the Select Files or Folders dialog
After choosing the Left and Right files, click Select next to the Filter field.
In the Filters dialog, use the Linefilters tab to enable the line filters you want to use (if any), or to see what line filters are currently enabled.
The Filter field does not indicate what line filters are enabled.
Proceed with the file compare operation. The enabled line filters are applied when you start the operation.
After you have already launched a file compare operation (for example, to apply different filters or disabling filtering)
Click Tools → Filters.
Open the Filefilters tab.
Check the individual line filters you want to apply, and uncheck filters that you don't want to apply.
You can also add, edit, and remove filters from the list by using the New, Edit, and Remove buttons.
To turn on line filtering, check the Enable Line Filters. To turn line filtering off, uncheck the option.
Click OK to dismiss the File Filters dialog.
Click F5 to apply your changes and refresh the File Compare window.
A line filter is a rule that is evaluated against each single-line difference in your compared files, if line filter rules are enabled. When a rule matches a single-line difference, the difference is ignored.
Ignored differences are marked in the File Compare window with the Ignored Difference color (as defined in the Colors page of WinMerge Options). This enables you to distinguish ignored differences from other types. However, you cannot select or merge ignored difference.
Line filter matching can be described in terms of two ideas:
When a rule matches any part of the line, the entire difference is ignored. Therefore, you cannot filter just part of a line. For example, suppose two files have the following single-line difference:
# Jean Sibelius
# Janne Sibelius
With no filtering, the line is detected as a difference. But if we apply a line filter rule with the expression,
^#, the lines are reported as identical, because the expression specifies only the first character, which matches in both files.
A rule is applied to a multi-line difference only if all the lines match. For example, consider this two-line difference:
# Jean Sibelius # Pekka Himanen
# Janne Sibelius Pekka Himanen
^#rule matches the first line, but not the second line. Therefore, the difference is not ignored.
It's usually good practice to use the beginning of line (
Example 3. Sample line filters
Filters lines that exactly match
Filters lines beginning with
Filters lines beginning with
/* and ending with
Filters lines beginning with numbers 100, 200, 300, 400, and 500
Example 4. Line filter rule matching CVS Id lines
CVS Id lines look like this:
// $Id: Filters.xml 7590 2013-01-20 05:57:16Z christianlist $
... and can be filtered with this rule:
^// \WId: .*\$
Example 5. Filter line number comments in po files
po line number comments look like this:
... and can be filtered with this rule:
This section describes the Filters dialog, which provides functions to create and manage file filters and line filters.
To open the Filters dialog, use either of these methods:
In the Select Files or Folders dialog, click Select to the right of the Filter field. You use this method when you want to apply a file filter to a folder compare operation.
Click Tools → Filters. This method can be used at any time except when the Select Files or Folders dialog is open.
The Filters dialog has a tab for each type of WinMerge filter:
The main part of this tab is a list of file filters that are available for folder compare operations. The list includes shared, private, and installed file filters that WinMerge knows about, as described in File filter locations.
You must enable a file filter to make it available in a folder comparison operation, or to disable a current filter to stop it from being used:
Open the Filters dialog, if it is not already open.
Select a file filter or <None> from the list.
Click OK to dismiss the Filters dialog.
There are several ways to apply file filters after enabling them. For details, see Applying file filters.
Use these buttons to manage your Filefilters list and create new file filters:
Your changes are saved when you click OK to dismiss the Filters dialog. Line filters are stored in the Windows registry.
If the file filters that are installed with WinMerge do not provide the filtering you need, you can create your own:
Click Tools → Filters. Or, from the Select Files or Folders dialog, click Select to the right of the Filter field.
In the Shared or Private Filter dialog, choose Shared Filter or Private Filter (see File filter locations for their uses) and click OK.
The Select filename for new filter dialog opens in the shared or private files folder on your system (if the private folder does not exist, WinMerge creates it).
In the Select filename for new filter dialog, enter a new file name and click Save.
Don't choose an existing file name: to edit an existing file, go back to Step 2 and click Edit instead of New.
WinMerge initializes the new file with the contents of the
FileFilter.tmpltempate, and opens it in your default text editor.
Follow the template instructions to edit the template, updating the placeholder name and description and adding filter rules as described in File filter syntax. Save the file in your text editor.
If you want to quickly test a rule that you are defining, try clicking Test in the Filters dialog. See Testing file filter rules for details.
If you created your file filter in one of the standard
Filtersfolders, and the Filters dialog does not list your new file filter, try clicking OK to close it, then click Tools → Filters again to reopen it. The Filefilters list should now include the new file filter.
If you saved the file in an alternate location on your file system), WinMerge cannot detect it unless you install it. To make a file filter detectable anywhere on your system:
Click Install in the Filters dialog.
In the Locate filter file to install dialog, navigate to the
fltfile on your system, and click Open. The Filefilters list should now include the installed file filter.
Use the Test Filter dialog to quickly test a file filter against sample data, to help you develop new rules or to understand how existing rules work. It can be easier than running a full compare operation.
Starting from the Filters dialog:
In the Filefilters tab, choose the file filter you want to test.
If you want to see the rules you will be testing,click Edit now to open the file so that you can view it during the next steps.
In the Test Filter dialog, choose the type of rule to test:
To test an f: file rule in your file filter, uncheck the Folder Name option.
To test a d: folder rule, check the Folder Name option.
Enter the text to test.
The text should be appropriate for the type of rule you are testing. For example, if you have checked the Folder Name option, you probably want to enter a folder name, such as \temp.
The Result box displays your entry, followed by its status: either
Use this tab to configure and enable line filters for file compare operations. The tab features a list of rules. Each rule contains a single regular expression. You can apply any combination of rules from the list to a file comparison.
Below the Regular Expressions list is an edit box and buttons that you can use to maintain the list at any time by adding, editing, and removing rules.
To add a new rule:
Click New. Your edit cursor is automatically enabled in the edit box.
Enter an expression in the edit box below the Regular Expressions list.
Click Save to load the expression in a new line in the list.
To edit an existing rule:
Select the line and click Edit.
Edit the expression in the edit box.
Click Save when you're done.
To delete an existing rule, select (check) the rule and click Remove.
In the Regular Expressions list, check just the filters that you want to apply, and uncheck any filters you do not want to apply.
Check or uncheck the Enable Line Filters option. If you turn filtering on, all the rules that are currently checked in the Regular Expression list are used. If filtering is off, no rules are used even if they are checked.
Click OK to dismiss the Filters dialog and save your settings.
There are several ways to apply file filters after enabling them. For details, see Applying line filters.
Regular expressions can be very complex. Fortunately, most file filters in WinMerge involve simple extension expressions, as shown in the examples in this topic. The filter files installed with WinMerge include many other useful examples.
Finally, there are lots of resources on the Web for help with regexps, including these sites:
- Good site devoted to regexps:
- PDF quick reference: