.. _exclusion markers:

Exclusion Markers
=================

.. program is needed to resolve option links
.. program::  gcovr

You can exclude parts of your code from coverage metrics.

- If ``GCOVR_EXCL_LINE`` appears within a line,
  that line is ignored.
- If ``GCOVR_EXCL_START`` appears within a line,
  all following lines (including the current line) are ignored
  until a ``GCOVR_EXCL_STOP`` marker is encountered.
- If ``GCOVR_EXCL_FUNCTION`` in the line of the function definition
  but not in front of the definition, the lines of the function are
  ignored. This marker needs the ``gcov`` JSON format version 2 which
  is generated by ``gcc-14``. If the needed info isn't available a
  warning is printed if the tag is found. Also a warning is printed
  if no function is defined at the tag location.
  See also :option:`--exclude-function`
- If ``GCOVR_EXCL_BR_*`` markers are used the same exclusion rules
  apply as above, with the difference being that they are only taken
  into account for branch coverage.
- If ``GCOVR_EXCL_BR_SOURCE`` the branches which have one of the block
  ids of the current line as destination block are excluded from the
  coverage. This can be used e.e. in a ``default`` branch which is used
  for error handling to exclude the source branch from the coverage.

Instead of ``GCOVR_*``,
the markers may also start with ``GCOV_*`` or ``LCOV_*``.
However, start and stop markers must use the same style.
The prefix is configurable with the option
:option:`--exclude-pattern-prefix<gcovr --exclude-pattern-prefix>`.

The excluded region not includes the line with the stop marker::

    code
    code
    excluded       // GCOVR_EXCL_START
    still excluded
    ...
    still excluded
    NOT excluded // GCOVR_EXCL_STOP
    code
    code

In the excluded regions, *any* coverage is excluded.

.. versionadded:: 8.0
    If :option:`--verbose<gcovr --verbose>` is used the exclusion ranges are logged.