Gcovr tries to only report coverage for files within your project, not for your libraries. This is influenced by the following options:
- (the current working directory where gcovr is invoked)
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:
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
$at the end ensures that the path ends here.
-f/--filter is provided,
-r/--root is turned into a default filter.
Therefore, files outside of the
directory are excluded.
To be included in a report, the source file must match any
and must not match any
--gcov-exclude filters apply to the
.gcov files created by
This is useful mostly when running gcov yourself,
and then invoking gcovr with
But these filters also apply when gcov is launched by gcovr.
Speeding up coverage data search¶
--exclude-directories filter is used
while searching for raw coverage data (or for existing
.gcov files when
-g/--use-gcov-files is active).
This filter is matched against directory paths, not file paths.
If a directory matches,
all its contents (files and subdirectories) will be excluded from the search.
For example, consider this build directory:
build/ ├─ main.o ├─ main.gcda ├─ main.gcno ├─ a/ │ ├─ awesome_code.o │ ├─ awesome_code.gcda │ └─ awesome_code.gcno └─ b/ ├─ better_code.o ├─ better_code.gcda └─ better_code.gcno
If we run
gcovr --exclude-directories 'build/a$',
this will exclude anything in the
but will use the coverage data for
This can speed up gcovr when you have a complicated build directory structure.
Consider also using the
--object-directory arguments to specify
where gcovr starts searching.
If you are unsure which directories are being searched,
run gcovr in
For each found coverage data file gcovr will invoke the
This is typically the slowest part,
and other filters can only be applied after this step.
In some cases, parallel execution with the
might be helpful to speed up processing.
Filters for symlinks¶
Gcovr matches filters against real paths that have all their symlinks resolved. E.g. consider this project layout:
/home/you/ ├─ project/ (pwd) │ ├─ src/ │ ├─ relevant-library/ -> ../external-library/ │ └─ ignore-this/ └─ external-library/ └─ src/
has the real path
To write a filter that includes both
we cannot use
because that contains a symlink.
Instead, we have to use an absolute path to the real name:
gcovr --filter src/ --filter /home/you/external-library/src/
or a relative path to the real path:
gcovr --filter src/ --filter '\.\./external-library/src/'
New in version 5.1: gcovr also supports symlinks/junctions/drive substitutions on Windows.
More examples for filters¶
Excluding files inside build directory via --exclude with absolute path (Unix only):
Excluding files inside build directory via --filter with relative path: