For Codecov to operate properly, all files paths in the coverage report must match the git/hg file structure. This approach is how Codecov is able to correctly map coverage information in your uploaded coverage reports to the corresponding files in your repository.

It is incredibly common, and encouraged, for users to run tests in their CI environments and then upload coverage directly to codecov as a step in their CI process. This can lead to problems, however, because the paths to files in a coverage report generated during CI will map to the CI's file system. This mapping may not necessarily map to the file structure of your project in git/hg. When this is the case, Codecov will fail to properly process your reports. Codecov's path fixing feature was built to address this problem.

An Example of Path Fixing

For example, CircleCI, will clone your project to home/circleci/project and run all tests relative to that directory, meaning your generated coverage report will reference a file as /home/circleci/project/path/to/ which doesn't match the path /project/path/to/ in your project.

In many cases, such as with CircleCI above, Codecov has internal methods of mapping paths, so the user is never even aware that paths are being modified in order to map coverage information to their project correctly. However, it is impossible for Codecov to do this for every CI and/or build scenario engineering teams may use.

How to Provide Path Fixes Manually

In the event that your files are failing to process, Codecov provides path fixing to allow engineering teams to manually map the file paths in their coverage reports to their project's git/hg structure.

Teams can update a repo level codecov.yml to concretely specify:

- <files in coverage report>::<corresponding paths in git/hg project>

The path fixing options are as follows:

  - "before/::after/"  # move path   e.g., "before/path" => "after/path"
  - "::after/"         # move root   e.g., "path/" => "after/path/"
  - "before/::"        # reduce root e.g., "before/path/" => "path/"

Regexp and glob pattern matching are allowed in the fixes:

  - "before/test-*::after/"

The pattern above will move files in the following manner.

before/tests-apples/test.js => after/test.js
before/tests-oranges/test.js => after/test.js
before/app-apples/app.js => before/app-apples/app.js

As a concrete use case, using the CircleCI example above, Codecov provides the following path fix automatically for CircleCI users:

   - "/home/circleci/::"

How do I know if I should use Path Fixing?

Generally if your uploaded reports fail to process, path fixing may help. You should download the coverage report generated within your CI for a particular commit, examine the file paths located within it, and see if they map directly to your git/hg file structure. If not, you can attempt to apply a path fix and see if this helps on subsequent commits.

Disable default path fixing

To disable Codecov's built-in path fixing, you can add the following to your codecov.yml file.

  disable_default_path_fixes: false