diff-cover

library10.2.0pypypiunverified

Diff-Cover is a command-line tool that enhances code review by reporting test coverage and linting violations specifically on new or modified lines within a Git diff. It compares an XML coverage report (e.g., Cobertura, Clover, JaCoCo, or LCov format) with the output of `git diff` to highlight lines that lack test coverage or contain quality issues. The library is currently at version 10.2.0 and maintains an active release cadence with frequent updates and dependency bumps.

testing devops

pip install diff-cover

github ↗package ↗

INSTALL

IMPORT

SIG · DIFF-COVER

diff-cover

testingpythonv10.2.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

This quickstart demonstrates the core functionality of `diff-cover`. First, ensure you have a Git repository and a `coverage.xml` report generated by a tool like `coverage.py` or `pytest-cov`. The `diff-cover` command then compares this report against your Git changes to identify uncovered or problematic lines in the diff.

git init # Create some dummy files and commits for a diff echo "def func1():\n pass" > file1.py git add file1.py git commit -m "Initial commit" echo "def func2():\n return 1 # new line" >> file1.py git add file1.py git commit -m "Add func2" # Run your tests with coverage and generate an XML report # (Requires pytest-cov and pytest to be installed) # For a real project, this would run actual tests pytest --cov=. --cov-report=xml --ignore=file1.py # Now, run diff-cover on the generated coverage.xml against the latest diff # This example might report 'No lines with coverage information in this diff.' # if the dummy coverage report doesn't perfectly align with the diff. # In a real scenario, `pytest --cov` would cover the changed lines. diff-cover coverage.xml

diff-cover --version

Debug

Known issues

breakingVersion 10.1.0 updated the minimum required Python version to `>=3.10`. Version 10.0.0 explicitly dropped support for Python 3.9 while adding support for Python 3.14. Users on older Python versions (e.g., 3.9 or earlier) must upgrade their Python environment or use an older `diff-cover` version.

fix

Upgrade your Python environment to 3.10 or newer. If you must use Python 3.9 or older, pin `diff-cover<10.0.0`.

affects: >=10.0.0

gotcha`diff-cover` relies on source file paths matching exactly between the coverage report and the Git diff. Mismatched relative paths are a common cause of 'No lines with coverage information in this diff.' errors. Version 10.2.0 added support for converting violation paths to relative paths for subfolder support. Version 9.7.2 fixed file name matching on Windows.

fix

Ensure `diff-cover` is run from the same working directory where the coverage report (e.g., `coverage.xml`) was generated. Verify that file paths in the coverage report align with your Git repository structure. Consider updating to `diff-cover>=10.2.0` for improved subfolder handling.

affects: All versions, improved in 9.7.2, 10.2.0

gotcha`diff-cover` may not accurately analyze changes within multi-line statements because coverage reports typically list code statements rather than every changed line. This can lead to lines changed in the diff not being reported in coverage.

fix

Use the `--expand-coverage-report` argument (available for XML reports) to add lines not appearing in the coverage report to them, allowing for a more comprehensive diff coverage analysis. Be aware this workaround assumes coverage tools report untested statements with 0 hits.

affects: All versions

deprecatedIn version 10.0.0, the `include` and `exclude` arguments were normalized to accept both a string or a list. While this is generally an improvement, older configurations expecting only one type might behave unexpectedly if not reviewed.

fix

Review existing configurations for `include` and `exclude` patterns. Update them to either a string or a list of strings, ensuring they work as intended with the new normalized behavior.

affects: >=10.0.0

gotchaOlder versions of `diff-cover` had compatibility issues with Ruff, particularly when Ruff versions >= 0.12.9 were used, requiring a forced Pylint output format. While fixed in v9.7.0 and v9.7.1, users integrating Ruff should be aware.

fix

Upgrade to `diff-cover>=9.7.1` to ensure proper compatibility with Ruff, especially with newer versions of Ruff. If unable to upgrade, you might need to configure Ruff to output in a Pylint-compatible format explicitly.

affects: <9.7.1

gotcha`diff-cover` no longer declares optional dependencies (extras) like 'flake8', 'mypy', 'pylint', or 'ruff'. Users expecting to install these dependencies via `pip install diff-cover[extra_name]` will find that these extras are not provided.

fix

Install required linting tools manually (e.g., `pip install ruff`) alongside `diff-cover`, as `diff-cover` no longer manages their installation through extras.

affects: >=10.0.0

Errors

Common errors & fixes

No lines with coverage information in this diff.

This error occurs when diff-cover cannot match source files in the generated XML coverage report with the files identified in the Git diff, often due to relative path mismatches or incorrect working directories during report generation or diff-cover execution.

fix

Ensure that diff-cover is run from the same working directory where your coverage tool (e.g., coverage.py) generated the XML report, so that file paths in the report align with Git's paths. For multi-module projects, use the `--src-roots` argument to specify the correct base directories for your source code.

fatal: ambiguous argument 'origin/main...HEAD': unknown revision or path not in the working tree.

This error indicates that Git, when invoked by diff-cover, cannot find the specified branch to compare against (e.g., 'origin/main' or 'origin/master'), possibly because the remote branch doesn't exist, hasn't been fetched, or the local repository is in a detached HEAD state.

fix

First, ensure your remote branches are up-to-date by running `git fetch origin`. Then, verify the branch name you are comparing against is correct and exists. You can explicitly specify an existing branch using the `--compare-branch` argument, e.g., `diff-cover coverage.xml --compare-branch=your_base_branch`.

Error: No XML reports found

diff-cover requires an XML coverage report (e.g., coverage.xml) in a supported format (Cobertura, Clover, JaCoCo, LCov), and this error indicates that the tool could not locate the specified report file or that the report was empty/malformed.

fix

Verify that your test runner is correctly configured to generate a coverage report in a supported XML format and that the path to this report file is correctly passed to the `diff-cover` command. For example, when using `pytest-cov`, generate the report with `pytest --cov --cov-report=xml` and then run `diff-cover coverage.xml`.

Upgrade

Version history

10.2.0latest on PyPI · released Jan 9, 2026

Audit

Dependencies

coverage.pyrequiredCommonly used Python test runner to generate coverage reports, typically in XML format.

pytest-covrequiredPytest plugin for generating coverage reports.

flake8optionalOptional quality checker for Python code.

mypyoptionalOptional static type checker for Python.

pylintoptionalOptional static code analyzer for Python.

ruffoptionalOptional fast Python linter, supports Pylint output format for diff-cover.

Agent activity

17 hits · last 30 days

node

Resources

githubhttps://github.com/Bachmann1234/diff-cover ↗

packagehttps://pypi.org/project/diff-cover/ ↗