.\" Man page generated from reStructuredText .\" by the Docutils 0.23 manpage writer. . . .nr rst2man-indent-level 0 . .de1 rstReportMargin \\$1 \\n[an-margin] level \\n[rst2man-indent-level] level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] - \\n[rst2man-indent0] \\n[rst2man-indent1] \\n[rst2man-indent2] .. .de1 INDENT .\" .rstReportMargin pre: . RS \\$1 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] . nr rst2man-indent-level +1 .\" .rstReportMargin post: .. .de UNINDENT . RE .\" indent \\n[an-margin] .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] .nr rst2man-indent-level -1 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. .TH "HTML2LCOV" "1" "2026-10-03" "2.6" "LCOV" .SH NAME html2lcov \- html2lcov documentation .INDENT 0.0 .TP .B Manual section 1 .TP .B Manual group LCOV Tools .UNINDENT .SH NAME .INDENT 0.0 .TP .B html2lcov Recover lcov \fB\&.info\fP coverage data and a source diff from an HTML report .UNINDENT .SH SYNOPSIS .INDENT 0.0 .INDENT 3.5 .sp .EX html2lcov [\-\-output filename] [\-\-source\-directory dir]+ [\-\-current\-file file]+ [options] report_directory+ .EE .UNINDENT .UNINDENT .SH DESCRIPTION .sp \fBhtml2lcov\fP screen\-scrapes a \fBgenhtml\fP\-generated HTML coverage report to recover: .INDENT 0.0 .IP \(bu 2 The LCOV \fB\&.info\fP coverage data that was used to produce the report. \fBgenhtml\fP copies its input \fB\&.info\fP files into the top level of the report directory when it is run with \fB\-\-save\fP; \fBhtml2lcov\fP finds and aggregates those files, using the same layout definition that \fBgenhtml \-\-save\fP uses to write them (so the reader and writer cannot drift). It is an error if the report does not contain any such \fB\&.info\fP file. .IP \(bu 2 The source code that was embedded in the per\-file HTML pages. This is compared against the source found under \fB\-\-source\-directory\fP to produce a universal diff and a human\-readable difference report. Note that \fBhtml2lcov\fP needs to see all of the original source code: the input HTML report must not be a subset report containing only part of the source code (\fIi.e.\fP, not a report generated using a \fB\-\-select\-script\fP callback). .UNINDENT .sp The source directory may contain new files that were not in the report, and may omit files that were in the report; these differences are documented in the difference report rather than being treated as errors. It is an error if the source directory contains no file that matches any file in the report. .sp Because \fBgenhtml\fP expands tabs and normalizes some whitespace when it renders source into HTML, the comparison is run with \fBdiff \-b\fP, which ignores differences in the amount of whitespace (a tab and any run of spaces compare equal), so re\-indented or tab\-vs\-space\-only changes do not appear as spurious differences. .SH USE CASES .sp The common use case for \fBhtml2lcov\fP is when the user has code and/or test changes in their sandbox, has a coverage report from earlier in the day, and now wants to see whether subsequent changes are adequately tested. Unfortunately: the user isn’t entirely sure what the code looked like when the report was generated \- and does not have a corresponding label. In that case: file diffs and baseline coverage data can be extracted from the report, and then used as the \fBgenhtml\fP \fB\-\-diff\-file\fP and \fB\-\-baseline\-file\fP inputs. .sp Another common case is when some or all of the source code is generated and not under revision control \- but the user wants to verify that it is properly tested after configuration and/or generator changes. .SH OPTIONS .sp \fBhtml2lcov\fP supports the options that are common to the other tools in the LCOV suite, and honours the corresponding \fBlcovrc(5)\fP settings. In particular: .INDENT 0.0 .IP \(bu 2 file selection and path manipulation: \fB\-\-include\fP, \fB\-\-exclude\fP, \fB\-\-erase\-functions\fP, \fB\-\-substitute\fP, \fB\-\-filter\fP, \fB\-\-omit\-lines\fP, \fB\-\-demangle\-cpp\fP\&. These apply to the coverage data recovered from the report exactly as they do when the same data is read by \fBlcov\fP \- so a file which is excluded is also absent from the universal diff and from the difference report. .IP \(bu 2 parallelism and resource limits: \fB\-\-parallel\fP (\fB\-j\fP), \fB\-\-memory\fP, \fB\-\-tempdir\fP, \fB\-\-preserve\fP\&. \fBhtml2lcov\fP forks children both to read the report’s saved \fB\&.info\fP file(s) and to scrape and diff the report’s source pages, so \fB\-\-parallel\fP speeds up both phases of a large report; see PARALLELISM\&. .IP \(bu 2 message control and diagnostics: \fB\-\-ignore\-errors\fP, \fB\-\-keep\-going\fP, \fB\-\-expect\-message\-count\fP, \fB\-\-msg\-log\fP, \fB\-\-quiet\fP, \fB\-\-verbose\fP, \fB\-\-debug\fP\&. .IP \(bu 2 configuration and provenance: \fB\-\-config\-file\fP, \fB\-\-rc\fP, \fB\-\-comment\fP, \fB\-\-version\fP, \fB\-\-help\fP\&. .UNINDENT .sp The tool\-specific options are: .INDENT 0.0 .TP .B \fB\-\-output\fP \fIfilename\fP, \fB\-o\fP \fIfilename\fP Name a \fIbase\fP for the output files. Any extension is stripped from \fIfilename\fP to form \fIbase\fP, and each artifact then appends its own extension: the aggregated coverage is written to \fIbase\fP\fB\&.info\fP, the human\-readable difference report to \fIbase\fP\fB\&.rpt\fP, the universal diff to \fIbase\fP\fB\&.udiff\fP (unless \fB\-\-diff\-file\fP redirects it), and the profile (if \fB\-\-profile\fP is used) to \fIbase\fP\fB\&.json\fP\&. When \fB\-\-output\fP is omitted \fIbase\fP is \fBhtml2lcov\fP and the universal diff is written to standard output. .TP .B \fB\-\-source\-directory\fP \fIdir\fP Search \fIdir\fP for the current source files to diff against the report’s embedded source. May be used more than once. Files are matched by their path relative to the report’s recovered source root. When \fB\-\-source\-directory\fP is not specified it defaults to \fB\&.\fP (the current directory). .TP .B \fB\-\-current\-file\fP \fIfilename\fP An lcov \fB\&.info\fP file whose \fBSF:\fP records name the current source files. May be specified more than once, and each value may itself be a list separated by the configured list separator (see \fBlcovrc(5)\fP). .sp When any \fB\-\-current\-file\fP is given, its union of \fBSF:\fP paths becomes an authoritative whitelist of the current source files: .INDENT 7.0 .IP \(bu 2 Only files named in a \fBSF:\fP record may appear in the universal diff (as \fIchanged\fP or \fIadded\fP). Every other file found under \fB\-\-source\-directory\fP is ignored. .IP \(bu 2 A file present in the report (baseline) but \fBnot\fP in the current set is treated as \fIremoved\fP\&. .IP \(bu 2 A file present in the current set but \fBnot\fP in the report is treated as \fIadded\fP\&. .UNINDENT .sp \fBhtml2lcov\fP uses the \fB\&.info\fP only as a file list; its coverage data is not merged into any output. The expected workflow is to feed the \fBhtml2lcov\fP universal diff to \fBgenhtml \-\-diff\-file\fP and the aggregated \fB\&.info\fP output to \fBgenhtml \-\-baseline\-file\fP, using this same \fB\-\-current\-file\fP \fB\&.info\fP as the \fBgenhtml\fP \fIcurrent\fP input. .sp A current \fBSF:\fP path is matched to a report file when it equals either the report file’s recovered path or its report\-root\-relative path (after any \fB\-\-substitute\fP rules are applied); relative and absolute path styles are preserved on output. If a file appears in both sets under names that differ only in path (a shared basename or path tail), \fBhtml2lcov\fP emits an ignorable \fBmismatch\fP warning. Use \fB\-\-substitute\fP (or an external tool such as \fBsed(1) \%\fP) to reconcile path differences the tool cannot resolve on its own. .sp If a \fBSF:\fP path names a file that cannot be read from disk under \fB\-\-source\-directory\fP, \fBhtml2lcov\fP reports an ignorable \fBsource\fP error; when that error is ignored, the file is dropped from the universal diff and its record is removed from the aggregated \fB\&.info\fP output. .sp A missing \fB\-\-current\-file\fP is a fatal error; an empty file raises an ignorable \fBempty\fP error; a non\-empty file that contains no \fBSF:\fP record is not an LCOV file and is a fatal error. .TP .B \fB\-\-diff\-file\fP \fIfilename\fP Write the universal diff to \fIfilename\fP instead of the default \fIbase\fP\fB\&.udiff\fP (or standard output when \fB\-\-output\fP is omitted). .TP .B \fB\-\-profile\fP [\fIfilename\fP] Write timing and statistics data as JSON to \fIfilename\fP (default is \fIbase\fP\fB\&.json\fP). .UNINDENT .sp See \fBlcov(1) \%\fP and \fBlcovrc(5) \%\fP for details of other supported options and configuration settings. .SH OUTPUTS .sp \fBhtml2lcov\fP produces up to four distinct artifacts: .INDENT 0.0 .IP \(bu 2 \fBuniversal diff\fP (\fIbase\fP\fB\&.udiff\fP) \- written to \fIbase\fP\fB\&.udiff\fP, or to standard output when \fB\-\-output\fP is omitted; \fB\-\-diff\-file\fP redirects it elsewhere. Standard \fBdiff \-u\fP format, so it can be consumed by \fBgenhtml \-\-diff\fP\&. Files only under \fB\-\-source\-directory\fP appear as additions (versus \fB/dev/null\fP); files only in the report appear as removals. May be empty when there are no code changes. For a changed file both diff headers (\fB\-\-\-\fP and \fB+++\fP) name the same path – the source path recovered from the report, which is exactly the \fBSF:\fP record in the aggregated \fB\&.info\fP – so \fBgenhtml\fP can associate the diff with the recovered baseline coverage. .IP \(bu 2 \fBaggregated coverage\fP (\fIbase\fP\fB\&.info\fP) \- the \fBcurrent\fP coverage recovered from the report’s saved \fB\&.info\fP file(s). .IP \(bu 2 \fBdifference report\fP (\fIbase\fP\fB\&.rpt\fP) \- a human\-readable table listing every changed, added, removed, and unchanged file, with added/deleted line counts. .IP \(bu 2 \fBprofile\fP (\fIbase\fP\fB\&.json\fP) \- timing/statistics data, when \fB\-\-profile\fP is used. .UNINDENT .SH PARALLELISM .sp Both of the expensive phases of \fBhtml2lcov\fP are parallelized, and both are governed by \fB\-\-parallel\fP (\fB\-j\fP) and \fB\-\-memory\fP: .INDENT 0.0 .IP \(bu 2 reading the \fB\&.info\fP file(s) saved in the report \- the same parallel parse that \fBlcov \-\-add\-tracefile\fP uses. .IP \(bu 2 scraping the source out of the report’s HTML pages and diffing it against \fB\-\-source\-directory\fP\&. Each child scrapes and diffs a group of files and returns only the classification and the udiff text, so the recovered source never accumulates in the parent. Files are grouped by the size of the HTML page each is scraped from, so that the groups cost roughly the same; a report with only a handful of files is processed in this process rather than paying for a fork. .UNINDENT .sp The output does not depend on \fB\-\-parallel\fP: the \fB\&.info\fP, \fB\&.udiff\fP and \fB\&.rpt\fP artifacts are identical for any value. .SH EXAMPLES .sp Recover coverage and diff current source against a saved report: .INDENT 0.0 .INDENT 3.5 .sp .EX # Generate coverage and an HTML report, saving the input .info files $ lcov \-\-capture \-d . \-o cov.info $ genhtml cov.info \-\-save \-o html_report # make code and/or test changes \&... # capture new coverage data $ lcov \-\-capture \-d . \-o current.info # Recover the .info data and diff the current source tree $ html2lcov \-o changes html_report \-\-source\-directory ./src \-\-current\-file current.info # \(aqchanges.udiff\(aq is the universal diff (diff \-u format) # \(aqchanges.info\(aq is the recovered coverage data # \(aqchanges.rpt\(aq is the human\-readable difference report # now generate a differential report \- to see what has changed: $ genhtml \-o differential \-\-baseline\-file changes.info \-\-diff\-file changes.udiff current.info .EE .UNINDENT .UNINDENT .sp Also see the \fBexample_html2lcov\fP in the \fIexample\fP directory \fB|ToolName|_HOME/share/lcov/example\fP: .INDENT 0.0 .INDENT 3.5 .sp .EX $ cd |ToolName|_HOME/share/lcov/example $ make example_html2lcov .EE .UNINDENT .UNINDENT .SH NOTES .sp Coverage cannot be recovered from a report that was built without \fB\-\-save\fP, because the \fB\&.info\fP files are not present in the report directory. \fBhtml2lcov\fP treats this as an error rather than attempting a lossy scrape of the coverage counts from the HTML. .sp If the source under \fB\-\-source\-directory\fP is identical to the source embedded in the report, there are no differences to emit. This is a normal, expected outcome (for example, when the current source has not changed since the report was built), so \fBhtml2lcov\fP reports it as a non\-fatal \fBempty\fP warning (\fBNo source code differences found\fP) and still exits successfully. Use \fB\-\-ignore\-errors empty\fP to suppress the warning entirely. .SH AUTHOR .sp Henry Cox <\%> .SH SEE ALSO .sp \fBlcov(1) \%\fP, \fBgenhtml(1) \%\fP, \fBgeninfo(1) \%\fP, \fBlcovrc(5) \%\fP .SH Copyright 2024-2026, LCOV Project .\" End of generated man page.