fcov

README

fcov

fcov is a tool that analyzes code coverage files, and generates reports in various formats. It currently supports Go coverage files, and text and Markdown formats.

It can be used to quickly visualize coverage on the command line, or made part of a CI pipeline to generate coverage reports that can be posted as comments in pull requests.

Installation

You can download a package for Windows, macOS and Linux from the releases page. Extract the archive and move the binary to a directory in your system's $PATH.

Alternatively, you can build your own binary with these instructions.

First, ensure that you have installed Git and the latest Go toolchain (at least version 1.24).

Then run:

go install go.hackfix.me/fcov/cmd/fcov@latest

Usage

The tool has a command-line interface.

Report

The report command reads one or more coverage files, and generates reports that can be written to stdout, or one or more files.

Options

• --filter: accepts one or more glob patterns in gitignore format for specifying package or file paths to include or exclude from coverage processing and the generated report.

• --filter-output: accepts one or more glob patterns in gitignore format for specifying package or file paths to include or exclude only from the generated report.

  That is, if a path is excluded with --filter, then the calculated coverage percentage might be affected, and the path will also not be displayed in the report. However, if the same path is only excluded with --filter-output but not --filter, then the coverage percentage will not be affected, and the path will only be hidden from the report.

  This behavior is useful if you want to show the correct global coverage, but only create a report of specific packages or files. For example, to only show files and packages changed in a pull request.

• --nest-files, --no-nest-files: enable or disable file nesting under packages. This is useful for removing the repetition of the package path from the files that belong to that package.
  Default: --nest-files

• --output / -o: Write the report to stdout, and/or one or more files. More than one value can be provided, separated by comma. If a value is either 'txt' or 'md', the report will be written to stdout in text or Markdown format, respectively. If a value is in the form of a filename, e.g. 'report.md', then it will be written to a file with the format inferred from the extension.
  Default: 'txt'

• --thresholds: Lower and upper thresholds separated by comma used to change the output depending on the coverage percentage. For example, this is used by the Markdown format to change the color of the badge and coverage indicators.
  Default: '50,75'

• --trim-package-prefix: Value to trim from the file path prefix in the output. This is useful for removing long and common package names, to keep the output tidier.

Examples

• Process a single coverage file using default options:

  $ fcov report coverage.txt
  

  This outputs a report in text format with files nested under each package:

  go.hackfix.me/fcov/app      100.00%
      app.go                               100.00%
      options.go                           100.00%
  go.hackfix.me/fcov/app/cli   83.33%
      cli.go                                91.67%
      report.go                             81.25%
  go.hackfix.me/fcov/cmd/fcov   0.00%
      main.go                                0.00%
  go.hackfix.me/fcov/parse    100.00%
      go.go                                100.00%
  go.hackfix.me/fcov/report   100.00%
      render.go                            100.00%
      report.go                            100.00%
  go.hackfix.me/fcov/types     80.00%
      types.go                              80.00%
  
  Total Coverage: 94.16%
  

• Process multiple coverage files using default options:

  $ fcov report coverage1.txt coverage2.txt ...
  

  Or using shell globbing:

  $ fcov report coverage*.txt
  

• Exclude generated Go files based on their extension:

  $ fcov report --filter '*[._]gen.go,*.pb.go' coverage.txt
  

  Make sure that the --filter value is quoted to prevent it from being interpreted by the shell.

  Note that multiple patterns can be separated with a comma, and the use of the range notation to match both *.gen.go and *_gen.go files. See the gitignore format documentation for other syntax examples.

• Exclude all files except the fcov/report package:

  $ fcov report --filter '*,!fcov/report' coverage.txt
  go.hackfix.me/fcov/report 100.00%
      render.go                          100.00%
      report.go                          100.00%
  
  Total Coverage: 100.00%
  

  The ! prefix can be used to negate a pattern.

• Exclude all files only from the report, except the fcov/report package:

  $ fcov report --filter-output '*,!fcov/report' coverage.txt
  go.hackfix.me/fcov/report 100.00%
      render.go                          100.00%
      report.go                          100.00%
  
  Total Coverage: 94.16%
  

  Note the difference in Total Coverage from the --filter example above. It is lower since all project files were used for calculating it, but only files in the fcov/report package are shown.

• Disable file nesting below packages:

  $ fcov report --filter-output '*,!fcov/report' --no-nest-files coverage.txt
  go.hackfix.me/fcov/report           100.00%
  go.hackfix.me/fcov/report/render.go 100.00%
  go.hackfix.me/fcov/report/report.go 100.00%
  
  Total Coverage: 94.16%
  

• Write the report to stdout in text format, and write it to a report.md file in Markdown format:

  $ fcov report --output 'txt,report.md' coverage.txt
  

• Output the report in Markdown format to stdout:

  $ fcov report --output md coverage.txt
  

  Here's what it looks like rendered:

  ---

  

  Package	Coverage
  go.hackfix.me/fcov/app app.go 100.00% options.go 100.00%	100.00%
  go.hackfix.me/fcov/app/cli cli.go 91.67% report.go 81.25%	83.33%
  go.hackfix.me/fcov/cmd/fcov main.go 0.00%	0.00%
  go.hackfix.me/fcov/parse go.go 100.00%	100.00%
  go.hackfix.me/fcov/report render.go 100.00% report.go 100.00%	100.00%
  go.hackfix.me/fcov/types types.go 80.00%	80.00%

  ---

  View the source of this README file to see the raw Markdown.

  You can use the --no-nest-files option to disable the collapsible element, and show each file on its own line:

  $ fcov report --output md --no-nest-files coverage.txt
  

  ---

  

  Package	Coverage
  go.hackfix.me/fcov/app	100.00%
  go.hackfix.me/fcov/app/app.go	100.00%
  go.hackfix.me/fcov/app/options.go	100.00%
  go.hackfix.me/fcov/app/cli	83.33%
  go.hackfix.me/fcov/app/cli/cli.go	91.67%
  go.hackfix.me/fcov/app/cli/report.go	81.25%
  go.hackfix.me/fcov/cmd/fcov	0.00%
  go.hackfix.me/fcov/cmd/fcov/main.go	0.00%
  go.hackfix.me/fcov/parse	100.00%
  go.hackfix.me/fcov/parse/go.go	100.00%
  go.hackfix.me/fcov/report	100.00%
  go.hackfix.me/fcov/report/render.go	100.00%
  go.hackfix.me/fcov/report/report.go	100.00%
  go.hackfix.me/fcov/types	80.00%
  go.hackfix.me/fcov/types/types.go	80.00%

  ---

• Use different coverage thresholds to change the color of the badge in the Markdown report. With the default thresholds of '50,75', a total coverage value below 50% will generate a red badge, between 50% and 75% a yellow badge, and above 75% a green badge. To set the lower threshold to 40% and upper to 60% run:

  $ fcov report --output md --thresholds '40,60' coverage.txt
  

• Trim a common package prefix:

  $ fcov report --trim-package-prefix go.hackfix.me/ coverage.txt
  fcov/app       100.00%
      app.go     100.00%
      options.go 100.00%
  fcov/app/cli    83.33%
      cli.go      91.67%
      report.go   81.25%
  fcov/cmd/fcov    0.00%
      main.go      0.00%
  fcov/parse     100.00%
      go.go      100.00%
  fcov/report    100.00%
      render.go  100.00%
      report.go  100.00%
  fcov/types      80.00%
      types.go    80.00%
  
  Total Coverage: 94.16%
  

License

MIT