14. Filters

There are two kinds of filters in WinMerge: file filters for filtering files and directories in directory 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/directory name or line.

Regexps can be very complex to read. Luckily most file filtering needs are for file extensions. Filters installed with WinMerge show how to filter file extensions.

14.1.1. Help with regexps

There are many guides and help sites in Web:

14.2. File filters

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

Tip

Ignored items have "Skipped" status in directory 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 directories or files are ignored.

14.2.1. Filter files

Filter files are normal text files, with an extension of .flt. Filter files must be placed in either:

  • "Filters" subdirectory in the WinMerge program directory. This is the recommended place.

  • "Winmerge/Filters" subdirectory in user profile. Under Windows XP, this might be C:\Documents And Settings\username\Local Settings\Application Data\WinMerge\Filters or C:\Documents And Settings\username\Application Data\WinMerge\Filters. This can be used to store personal filters for the individual user, or for a user who lacks the ability to write to the WinMerge program directory. This also is appropriate if backup & restore from an individual profile directory is desired.

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 directories that match rules in filter.

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

When using exclusive filter its worth noting that the filter must contain rule to include all wanted subdirectories. Usually its wise to use this rule to include all subdirectories:
d: \\*$ ## Subdirectories

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: \\directory$ ## Match given directory name

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

Note

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

So simple filters can be for example:

Example 6. 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' directories

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

Don't forget "$" at end. It marks end of directory- 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 7. 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

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

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 8. 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 9. 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 10. 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:

^#