documentation.help

Using Filters

From WinMerge

previous page next page

Using Filters

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:

Folder comparison: File masks and file filters

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 View → Show Skipped Items 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.

File comparisons: Line filters

Line filters are applied only to file compare operations. They let you ignore single line differences.

1. Using file masks

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.

1.1. Defining and applying file masks

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 -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.

1.2. File mask syntax and example

Use this syntax for file masks:

*.[extension][delimiter *.extension ...]

Valid delimiters are spaces, commas, colons or semicolons.

A mask with no extension ( *. ) selects files without any extension, such as README.

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

2. Using file filters

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.

2.1. File filter locations

WinMerge automatically detects file filters in these locations:

Filters subfolder in the WinMerge installation folder

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.

Default private filter folder

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, My Documents\WinMerge\Filters in Windows XP). 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.

2.2. Applying file filters

You can apply a file filter using any of these methods:

  • When you launch a folder compare from the Select Files or Folders dialog:

    1. After choosing the Left and Right folders, click Select next to the Filter field.

    2. In the Filters dialog, use the Filefilters tab to choose a file filter and load it in the Filter field.

      [Note] Note

      If a file filter is currently enabled, the selected file filter is already loaded in the Filter field.

    3. 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):

    1. Click Tools → Filters.

    2. In the Filters dialog, configure your new file filter setting, and click OK.

    3. 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.

2.3. File filter syntax

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:

name

The filter name that is listed in the Files dialog

def

The type of filtering to be applied. Specify one of these values:

include

Includes everything except items matching the specified rule.

exclude

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
[Tip] Tip

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:

f: regexp

matches for files, or

d: regexp

matches for folders

Among the many regexp special characters, the following are particularly important in file filter rules:

^ (beginning of line)

Frequently required for rules to work correctly.

$ (end of line)

Frequently required for rules to work correctly. For example: 

\.c$ ## matches only file names with the extension, c.
\.c  ## matches any extension beginning with c, like cpp and com.
\ (escape)

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 2. File filter rule examples

Some simple file filter 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
d: Temp$ ## Match *Temp folders (for example, FirstTemp)
d: Src ## Match *Src* folders

Some rules with more complex regular expressions:

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

3. Using line filters

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.

3.1. Applying line filters

You can apply line filters using any of these methods:

  • When you launch a file compare from the Select Files or Folders dialog

    1. After choosing the Left and Right files, click Select next to the Filter field.

    2. 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.

      [Note] Note

      The Filter field does not indicate what line filters are enabled.

    3. 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)

    1. Click Tools → Filters.

    2. Open the Filefilters tab.

    3. 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.

    4. To turn on line filtering, check the Enable Line Filters. To turn line filtering off, uncheck the option.

    5. Click OK to dismiss the File Filters dialog.

    6. Click F5 to apply your changes and refresh the File Compare window.

3.2. Line filter syntax

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.

[Tip] Tip

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 3. Sample line filters

^MYTAG$

Filters lines that exactly match MYTAG

^::

Filters lines beginning with ::

^/\**.\*/$

Filters lines beginning with /* and ending with */

^[1-5]00

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:

#: src/filename.c:766

... and can be filtered with this rule:

^#

4. Using the Filters dialog

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:

Filefilters

Choose this tab to work with file filters for folder compare operations.

Linefilters

Choose this tab to work with line filters for file compare operations.

4.1. Using the Filefilters tab

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.

4.1.1. Enabling and disabling file filters

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:

  1. Open the Filters dialog, if it is not already open.

  2. Select a file filter or <None> from the list.

  3. Click OK to dismiss the Filters dialog.

There are several ways to apply file filters after enabling them. For details, see Applying file filters.

4.1.2. Configuring file filters

Use these buttons to manage your Filefilters list and create new file filters:

Test

Select a file filter in the list and click Test to quickly see how the filter works. See Testing file filter rules for details.

Install

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.

New

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.

Edit

Select a file filter in the list and click Edit to open the file in your default editor.

Delete

Select a file filter in the list and click Delete to delete the file and remove it from the list. Yes, the file is really deleted!

Your changes are saved when you click OK to dismiss the Filters dialog. Line filters are stored in the Windows registry.

4.1.3. Creating a file filter

If the file filters that are installed with WinMerge do not provide the filtering you need, you can create your own:

  1. Click Tools → Filters. Or, from the Select Files or Folders dialog, click Select to the right of the Filter field.

  2. In the Filters dialog Filefilters tab, click New.

  3. 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).

  4. In the Select filename for new filter dialog, enter a new file name and click Save.

    [Note] Note

    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 tempate, and opens it in your default text editor.

  5. 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.

    [Tip] Tip

    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.

  6. 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 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:

    1. Click Install in the Filters dialog.

    2. In the Locate filter file to install dialog, navigate to the flt file on your system, and click Open. The Filefilters list should now include the installed file filter.

4.1.4. Testing file filter rules

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:

  1. In the Filefilters tab, choose the file filter you want to test.

  2. 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.

  3. Click Test.

  4. 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.

  5. 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.

4.2. Using the Linefilters tab

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.

4.2.1. Configuring line filters

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:

  1. Click New. Your edit cursor is automatically enabled in the edit box.

  2. Enter an expression in the edit box below the Regular Expressions list.

  3. Click Save to load the expression in a new line in the list.

To edit an existing rule:

  1. Select the line and click Edit.

  2. Edit the expression in the edit box.

  3. Click Save when you're done.

To delete an existing rule, select (check) the rule and click Remove.

4.2.2. Enabling and disabling line filters

  1. In the Regular Expressions list, check just the filters that you want to apply, and uncheck any filters you do not want to apply.

  2. 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.

  3. 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.

5. Getting help with regular expressions

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:
http://www.regular-expressions.info/
Tutorial:
http://www.zvon.org/comp/r/tut-Regexp.html
PDF quick reference:
http://www.night-ray.com/regex.pdf
previous page start next page