Using Filters

Gcovr tries to only report coverage for files within your project, not for your libraries. This is influenced by the following options:

NOTE: Filters can also be specified in the gcovr configuration file: Configuration Files

These options take filters. A filter is a regular expression that matches a file path. Because filters are regexes, you will have to escape “special” characters with a backslash \.

Always use forward slashes / as path separators, even on Windows:

  • wrong: --filter C:\project\src\

  • correct: --filter C:/project/src/

If the filter looks like an absolute path, it is matched against an absolute path. Otherwise, the filter is matched against a relative path, where that path is relative to the current directory or if defined in a configuration file to the directory of the file.

Examples of relative filters:

  • --filter subdir/ matches only that subdirectory

  • --filter '\.\./src/' matches a sibling directory ../src. But because a dot . matches any character in a regex, we have to escape it. You have to use additional shell escaping. This example uses single quotes for Bash or POSIX shell.

  • --filter '(.+/)?foo\.c$' matches only files called foo.c. The regex must match from the start of the relative path, so we ignore any leading directory parts with (.+/)?. The $ at the end ensures that the path ends here.

If no -f/--filter is provided, the -r/--root is turned into a default filter. Therefore, files outside of the -r/--root directory are excluded.

To be included in a report, the source file must match any -f/--filter, and must not match any -e/--exclude filter.

The --gcov-filter and --gcov-exclude filters apply to the .gcov files created by gcov. This is useful mostly when running gcov yourself, and then invoking gcovr with -g/--gcov-use-existing-files. But these filters also apply when gcov is launched by gcovr.

More examples for filters

Excluding files inside build directory via --exclude with absolute path (Unix only):

-e '/.*/build/'

Excluding files inside build directory via --filter with relative path:

--filter '\.\./'