14. Filters

There are two kinds of filters in WinMerge: file filters for filtering files and folders in folder compare and line filters for ignoring lines from files before comparing.

14.1. Regular expressions

Filters are based on regular expressions (regexps). Each line filter or file filter rule is regexp which is matched against file/folder name or line.

Regexps can be very complex to read. Luckily most file filtering needs are for file extensions. File filters installed with WinMerge have many useful examples.

14.1.1. Help with regexps

There are many guides and help sites in Web, for example:

14.2. File filters

A file filter is a set of rules saved to one file. Every file and folder is tested against all these rules before comparing. Files and folders that match the rules are excluded if it is an inclusive filter, or included if it is an exclusive filter.

[Tip] Tip

Ignored items have "Skipped" status in folder compare. User can select them to visible or hidden from View menu. Usually its wise to keep skipped items hidden.

WinMerge's filtering system allows only one filter set to be active at a time. Active filter set can be selected from Open-dialog or from menu: Tools->Filters. Also empty filter can be selected when no folders or files are ignored.

Filtered out files get only minimal needed attention by the folder compare. This means that WinMerge misses a lot of information it gets for non-ignored files. For example there is no way to know if filtered file is a text file or a binary file. The reason is simple: as user tolds WinMerge one does not care about the file, WinMerge tries to minimize the effort and time for the file.

14.2.1. Filter files

Filter files are normal text files, with an extension of .flt. Files have defined format which is explained later in this chapter. Filters-dialog allows creating new filter files based on template file. Filter files can be created from the scrach but using template file is the recommended way to create a new filter. The template file is named FileFilter.tmpl and can be modified if needed. The template file is located in WinMerge/Filters -folder.

Filter files have two possible locations:

  • "Filters" subfolder in the WinMerge program folder. E.g. C:\Program Files\WinMerge\Filters.

  • User-defined folder. Selected in Options (Edit->Options->System+Filter Folder). By default it is My Documents\WinMerge\Filters folder.

[Important] Important

With WinMerge 2.6.0 and later filter files are not anymore loaded from profile folder like with earlier versions. Using user-defined folder for filter files provices more flexibility and easier access to filter files.

First part of filter file defines name and basic functionality of the filter:

name: Example filter
def: include

where def: is:

  • include - inclusive filter. This filter type filters out files and folders that match rules in filter.

  • exclude - exclusive filter. This filter type lets through files and folders that match rules in filter.

When using exclusive filter its worth noting that the filter must contain rule to include all wanted subfolders. Usually its wise to use this rule to include all subfolders:

d: \\*$ ## Subfolders

There can be one filter rule in one line. And rule cannot be split to several lines. Common format for one filter line is like this:

f: \.ext$ ## Match files *.ext

or

d: \\folder$ ## Match given folder name

Rule begins with "f:" if it matches for filenames and "d:" if it matches for folder names. (d comes from "folder".) Filenames are given to filter as is, there are no special characters added. But for folder names there must be "\\" in begin of folder name. The resulting "\" char is a part of the folder name. This is done clearly to separate folder names and filenames. "##" is a comment separator, all characters in line after that are ignored by WinMerge.

[Note] Note

File filter rules are case-insensitive. Rule .\bat$ matches to winmerge.bat and compare.BAT.

So simple filters can be for example:

Example 7. Simple filefilter rules

f: \.cpp$ ## Match *.cpp files
f: \.h$ ## Match *.h files
f: ^My ## Match My*.* files
f: Dlg\. ## Match *Dlg.* files
d: \\test$ ## Match 'test' folders
d: ^\\Build$ ## Match 'Build' folders

Line begin or -end marker ("^" or "$") is usually required filter to work correctly. Dot in filename must be "escaped" with "\" so "\." means dot in filename.

[Note] Note

Don't forget "$" at end. It marks end of folder- or filename and without it rule may not work like expected. While "\.c$" matches with only filenames having extension .c "\.c" matches all extensions beginning with "c" (.cpp, .com, etc).

Since file filter rules are regular expressions more complex rules are also possible. Following few rules show some possibilities for more complex rules:

Example 8. More complex file filter rules

f: ^\.#.*$ ## .#filename.version files
f: Dlg\.c(pp)?$ ## *Dlg.c & *Dlg.cpp files
f: ^I.*\.h$ ## I*.h files
f: Srv[1-9]\.def$ ## *Srv1.def - *Srv9.def files
f: ^[h,k,m] ## h*.* & k*.* & m*.* files

WinMerge ignores most whitespace characters in rules definition lines. However comment must always start with one or more whitespace character (space or tabulator) and comment-marker (##). ## can be used as part of rule if there is no whitespace character before it.

14.3. Line filters

Line filters can be used to ignore single lines from compared files. Line filters are handy when user doesn't want to compare comments or certain generated code. For example version control system (time)stamps.

[Important] Important

Line filter rule ignores single line it matches. It is not possible to ignore partial lines or several lines with file filter rule.

In file compare ignored lines are shown with own colors to differentiate them from other differences. User can see these differences but cannot select or merge them.

Line filter rules are regular expressions like file filter rules. Since filter matches if any part of line matches it is usually recommended to add begin ("^") or end ("$") marker to rule. Or both markers if exact line is wanted to filtered.

[Tip] Tip

There are some troubles with "$" and end-of-line. One way to work-around these troubles is to use "\W$" when possible.

Rules can be added and edited in Filters-dialog (Menu: Tools->Filters). In editbox, give one rule per line. Compare results are not updated automatically after changing line filter rules. User can update compare results by selecting Edit->Refresh or F5.

Maximum length for linefilter (all lines in dialog) is 255 characters.

Example 9. Some example line filters

^MYTAG$

- Filters out lines being exactly "MYTAG"

^::

- Filters out lines beginning with "::"

^/\**.\*/$

- Filters out lines beginning with "/*" and ending with "*/"

^[1-5]00

- Filters out lines beginning with numbers 100, 200, 300, 400 & 500

Example 10. Line filter rule matching CVS "Id:" -lines:

Id-lines are like this:

// $Id: Filters.xml,v 1.14.2.2 2005/10/29 17:21:16 kimmov Exp $

And they can be filtered with rule:

^// \WId: .*\$

Example 11. Filter out line number comments in po files:

po line number comments are like this:

#: src/filename.c:766

And they can be filtered out with rule:

^#