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

.. _exclusion markers:

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

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`` and newer. 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`` appears within a line, 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.g. in a
  ``default`` branch which is used for error handling to exclude the
  source branch from the coverage.
- If ``GCOVR_EXCL_BR_WITHOUT_HIT: uncovered/total`` appears within a line,
  the uncovered branches are ignored, e.g. ``GCOVR_EXCL_BR_WITHOUT_HIT: 2/6``
  will exclude the 2 uncovered branches out of 6 branches in the line.
  If the uncovered or total branches doesn't match the branches in the line a
  error is logged and nothing is excluded.

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

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` is used the exclusion ranges are logged.

.. versionadded:: 8.0
    Comment ``GCOVR_EXCL_BR_SOURCE``.

.. versionadded:: 8.4
    Comment ``GCOVR_EXCL_BR_WITHOUT_HIT: uncovered/total``.