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 specify files to include in a folder comparison by using simple file masks, or, for more complex filtering, by applying multiple rules specified in a file filter. You cannot apply both a file mask and a file filter in the same operation.
Files and folders that are filtered are hidden in the result by default, which is typically what you want. You can click → to unhide filtered items, but the Folder Compare window shows only minimal information about them. For example, you cannot tell whether a skipped file is a text file or binary.
Line filters are applied only to file compare operations. They let you ignore single line differences.
Substitution filters are applied only to file compare operations. They replace the strings in the diff block with the specified strings, compare them, and ignore the diff block if the replacement results match. They are useful for ignoring large numbers of uninteresting changes.
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 1st and 2nd 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
-f flag 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:
[!](*.[extension]|folder mask\)[delimiter[!](*.extension|folder mask\) ...]
Valid delimiters are spaces, commas, colons or semicolons.
A mask with no extension ( *. ) selects files
without any extension, such as
README
In 2.16.19 and later, if you put an exclamation mark(!)
in front of a mask, files matching that mask will be excluded.
Also, a backslash(\) after the mask will cause
the mask to match folders instead of files.
Example 1. File mask
In this command-line example, the folder compare operation
includes only files with xml or
txt extensions. All other files are omitted:
WinMergeU c:\project\docs c:\temp /f
*.xml;*.txt
Example 2. Excluding folders (In 2.16.19 or later)
In this command-line example, the folder compare operation
excludes .git and
.vs folders:
WinMergeU c:\project\docs c:\temp /f
!.git\;!.vs\
File filters are text files with an extension
of 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
named 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
filters.
WinMerge automatically detects file filters in these locations:
This is where the predefined file filters are installed. For
example, C:\Program Files\WinMerge\Filters. You
can create or copy filter files in this location to make them
available to all users on your system.
Before creating a new file filter, see if the predefined ones already contain what you need. If not, you might find useful rule examples in the existing files.
The location of this folder is defined in the System page of
WinMerge options. By default, it is specified as a subfolder in your
user profile folder (for example, Documents in
Windows 10). Filters that are created or copied here are normally
visible only to you. If you create new file filters, you can copy
them here to keep them private.
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 1st and 2nd folders, click next to the Filter field.
In the Filters dialog, use the File Filters 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 → .
In the Filters dialog, configure your new file filter setting, and click .
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 -f flag 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 ## as
characters in a rule, omit the whitespace prefix.
The first two required lines of a file filter are:
The filter name that is listed in the Files dialog
The type of filtering to be applied. Specify one of these values:
Includes everything except items matching the specified rule.
Excludes everything except items matching the specified rule.
When you choose the exclude method, you must also add a d (directory) rule that specifies the subfolders. It's usually a good idea to specify all subfolders, like this:
d: \\*$ ## Subfolders
Don't confuse these terms. Remember, in file filters, an include rule does not specify what to include, it specifies what not to include. Similarly, exclude does not specify what to exclude, it specifies what not to exclude.
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:
regexpmatches for files, or
regexpmatches for folders
In 2.16.19 and later, the type designators f!: and d!: has been introduced to exclude some of the files or folders matched by f: and d:.
Among the many regexp special characters, the following are particularly important in file filter rules:
Frequently required for rules to work correctly.
Frequently required for rules to work correctly. For example:
\.c$ ## matches only file names with the extension,c. \.c ## matches any extension beginning withc, likecppandcom.
Forces special characters to match normal characters. For
example, to match a folder name, precede the folder backslash
delimiter with a backslash (\\). To match the dot in a
file name, specify a backslash followed by a dot
(\.).
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, f: \.bat$
matches winmerge.bat and
compare.BAT.
Example 3. File filter rule examples
Some simple file filter rules:
f: \.cpp$ ## Match*.cppfiles f: \.h$ ## Match*.hfiles f: ^My ## MatchMy*.*files f: Dlg\. ## Match*Dlg.*files d: \\test$ ## Matchtestfolders d: ^\\Build$ ## MatchBuildfolders d: Temp$ ## Match*Tempfolders (for example,FirstTemp) d: Src ## Match*Src*folders
Some rules with more complex regular expressions:
f: ^\.#.*$ ##.#filename.versionfiles f: Dlg\.c(pp)?$ ##*Dlg.cand*Dlg.cppfiles f: ^I.*\.h$ ##I*.hfiles f: Srv[1-9]\.def$ ##*Srv1.defto*Srv9.deffiles f: ^[h,k,m] ##h*.*,k*.*, andm*.*files
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 1st and 2nd files, click next to the Filter field.
In the Filters dialog, use the Line Filters 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 → .
Open the File Filters 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 , , and buttons.
To turn on line filtering, check the Enable Line Filters. To turn line filtering off, uncheck the option.
Click 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:
File1:
# Jean Sibelius
File2:
# 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:
File1:
# Jean Sibelius # Pekka Himanen
File2:
# Janne Sibelius Pekka Himanen
The same ^# 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 (
^ ) and end of line ( $ ) markers to
control your patterns precisely, because the rule is applied if any part
of a line matches the expression.
Example 4. Sample line filters
^MYTAG$
Filters lines that exactly match MYTAG
^::
Filters lines beginning with ::
^/\*.*\*/$
Filters lines beginning with
/**/
^[1-5]00
Filters lines beginning with numbers 100, 200, 300, 400, and 500
Example 5. Line filter rule matching CVS Id lines
CVS Id lines look like this:
// $Id: Filters.xml 7591 2013-01-20 15:47:42Z christianlist $
... and can be filtered with this rule:
^// \WId: .*\$
Example 6. Filter line number comments in po files
po line number comments look like this:
#: src/filename.c:766
... 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 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 → . 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:
Choose this tab to work with file filters for folder compare operations.
Choose this tab to work with line filters for file compare operations.
Choose this tab to work with substitution filters for file compare operations.
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 from the list.
Click 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 File Filters list and create new file filters:
Select a file filter in the list and click to quickly see how the filter works. See Testing file filter rules for details.
Enables you to locate a file filter and adds it to the Filters list. File filters that are not in either the shared or default private folder are not detected unless you install them.
Creates a new copy of a file template in either the shared or private filter folders, and opens it in your default editor. Edit the template and add your rules, as described in Creating a file filter.
Select a file filter in the list and click to open the file in your default editor.
Select a file filter in the list and click to delete the file and remove it from the list. Yes, the file is really deleted!
Your changes are saved when you click 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 → . Or, from the Select Files or Folders dialog, click 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 .
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.tmpl template, 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
Filters folders, and the Filters dialog does
not list your new file filter, try clicking
to close it, then click → again to reopen it. The
File Filters 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 in the Filters dialog.
In the Locate filter file to install dialog, navigate to
the flt file on your system, and click
. The File Filters 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 File Filters tab, choose the file filter you want to test.
If you want to see the rules you will be testing, click now to open the file so that you can view it during the next steps.
Click .
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
passed or
failed.
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 . Your edit cursor is automatically enabled in the edit box.
Enter an expression in the edit box below the Regular Expressions list.
Click to load the expression in a new line in the list.
To edit an existing rule:
Select the line and click .
Edit the expression in the edit box.
Click when you're done.
To delete an existing rule, select (check) the rule and click .
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 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: