.\" 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 "JACOCO2LCOV" "1" "2026-10-03" "2.6" "LCOV" .SH NAME jacoco2lcov \- jacoco2lcov documentation .INDENT 0.0 .TP .B Manual section 1 .TP .B Manual group LCOV Tools .UNINDENT .SH NAME .INDENT 0.0 .TP .B jacoco2lcov Translate JaCoCo execution data to lcov format .UNINDENT .SH SYNOPSIS .INDENT 0.0 .INDENT 3.5 .sp .EX jacoco2lcov [\-\-output mydata.info] [options] execfile+ .EE .UNINDENT .UNINDENT .SH DESCRIPTION .sp \fBjacoco2lcov\fP translates the execution data which JaCoCo collected while your Java tests ran into LCOV \fB\&.info\fP format. .sp It does none of the translation itself: it is a wrapper which runs, in order, the two commands you would otherwise run by hand \- .INDENT 0.0 .IP \(bu 2 \fBjava \-jar jacococli.jar report ... \-\-xml tmp.xml\fP, to turn the \fB\&.exec\fP execution data files into a JaCoCo XML report, and .IP \(bu 2 \fBxml2lcov \-\-format jacoco ... tmp.xml\fP, to translate that report into LCOV \fB\&.info\fP format \- .UNINDENT .sp and then reads the LCOV format \fB\&.info\fP file generated by \fBxml2lcov\fP, applies the common LCOV options \- filtering, exclusions, \fIetc.\fP \- and writes the result to the output file. The data is read and written by the same code every other tool in the suite uses, so \fBjacoco2lcov\fP supports every common option \- see \fBOPTIONS\fP\&. .sp The intermediate files are temporary and are removed when \fBjacoco2lcov\fP finishes; use \fB\-\-xml\fP to keep the XML report. .sp Either of the two steps can be run independently if you want or need to \- say, because you need additional options or flags that are not supported by the script. .sp \fBWhat JaCoCo needs to be told\fP .sp A JaCoCo \fB\&.exec\fP file holds execution data but not the names of the classes it refers to or their source. Thus, at least one class location has to be named, with \fB\-\-classpath\fP: JaCoCo reads the coverage counts out of the class files, and cannot write a report without them. At least one source directory has to be named as well, with \fB\-\-source\-directory\fP, because a JaCoCo report names no search path of its own and \fBxml2lcov\fP has to find the sources to translate them. \fB\-\-plugin\-directory\fP is a shorthand for both when your code is laid out in the usual Eclipse or Maven way. .sp With none of \fB\-\-classpath\fP, \fB\-\-source\-directory\fP and \fB\-\-plugin\-directory\fP given, the current directory is searched as \fB\-\-plugin\-directory .\fP would search it. That finds the source and class directories of a project laid out either of those ways \- \fBsrc/main/java\fP and \fBtarget/classes\fP for Maven, \fBsrc\fP and \fBbin\fP for Eclipse \- and of a directory holding several such projects, in which case each of them contributes the directories it has. \fBjacoco2lcov\fP says so when it does this, and stops if it finds nothing: a layout it does not recognize, or classes somewhere else your build put them, still has to be named. It is a convenience for the usual case, not a search: nothing is looked for outside the conventional places, and nothing is guessed from file extensions. .sp \fBCoverage types\fP .sp JaCoCo data always contains branch and function coverage \- so \fBjacoco2lcov\fP enables both of them by default. Use command line and/or config file options to change this behaviour, if desired. .sp There is no MC/DC or condition coverage to write: JaCoCo does not collect it. .sp \fBSource versions\fP .sp A JaCoCo report does not say which version of the source it describes, so there is no version in the data to carry through \- unlike a \fBlcov \-\-capture\fP, which records the version of each file it finds. \fB\-\-version\-script\fP therefore means “compute the version”, and \fBjacoco2lcov\fP turns \fBcompute_file_version\fP on for you when you name one: the callback is applied to each file as the translated data is read back in, and the \fBVER:\fP records it returns are written to the output. Say \fB\-\-rc compute_file_version=0\fP if you want the callback used for nothing but comparisons. .sp Without a version script there is no version to record, and a report generated from the result has nothing to check the source it reads against \- so \fBgenhtml(1) \%\fP will stop with a \fBversion\fP error if it is asked to compute versions itself. .sp \fBConsistency\fP .sp JaCoCo counts instructions and branches rather than executions, so the execution counts in the translated data are derived, and LCOV may consider the result internally inconsistent \- most often because JaCoCo reports a line as covered whose branches it never saw evaluated. See the \fBJaCoCo conversion notes\fP section of \fBxml2lcov(1) \%\fP for why the derived data appears as it does. If you need to work around the \fBinconsistent\fP error which is reported, either exclude the offending code or add \fB\-\-ignore\-errors inconsistent\fP to your command line. .sp The same \fBinconsistent\fP error is generated when a function is marked “not executed” but contains a line which is covered \- for example, \fBfunction \(aqcom.example.Widget.dead()V\(aq is not hit but line 8 is\fP\&. A JaCoCo \fBmethod\fP contains a ‘begin’ line but no information about where it ends \- so the range of lines contained within the function is derived from the line data and source text. This can erroneously claim a line belonging to another method. The message can be suppressed via \fB\-\-ignore\-errors inconsistent\fP\&. See the \fBJaCoCo conversion notes\fP section of \fBxml2lcov(1) \%\fP\&. .sp \fBMerging\fP .sp If you have execution data from more than one test run, hand all of the \fB\&.exec\fP files to a single \fBjacoco2lcov\fP command rather than translating each of them and merging the results with \fBlcov \-a\fP: JaCoCo can combine per\-branch data exactly and the translated data cannot. See \fBMerging JaCoCo data\fP in \fBxml2lcov(1) \%\fP\&. .SH OPTIONS .sp In addition to the common options supported by the other tools in the LCOV suite (\fIe.g.\fP, \fB\-\-exclude\fP, \fB\-\-include\fP, \fB\-\-filter\fP, \fB\-\-substitute\fP, \fB\-\-omit\-lines\fP, \fB\-\-erase\-functions\fP, \fB\-\-ignore\-errors\fP, \fB\-\-comment\fP, \fB\-\-version\-script\fP, \fIetc.\fP), which are applied to the translated data, the tool options are the ones below. .sp Each of them is marked optional or required, and the default of each is given. Nothing but the \fB\&.exec\fP files is required unconditionally: the rest of what \fBjacoco2lcov\fP has to know it can get from the environment or from the layout of the directory it is run in. .INDENT 0.0 .TP .B \fIexecfile\fP One or more JaCoCo \fB\&.exec\fP execution data files or directories which are searched for \fB\&.exec\fP files. Every argument which is not an option is taken to name execution data, whatever it is called: \fB\&.exec\fP is a convention and nothing here depends on it. Required. .TP .B \fB\-o\fP, \fB\-\-output\fP \fIfile\fP Optional. Specify the output LCOV \fB\&.info\fP file. Default: \fBjacoco2lcov.info\fP in the current directory. .TP .B \fB\-t\fP, \fB\-\-test\-name\fP, \fB\-\-testname\fP \fIname\fP Optional. Specify the test name for the \fBTN:\fP entry in the LCOV \fB\&.info\fP file. Default: none \- the \fBTN:\fP entry is empty. .TP .B \fB\-d\fP, \fB\-\-root\-directory\fP \fIdirectory\fP Optional. The run directory and root of relative paths to source, class execution data files, and the output file. Default: the directory \fBjacoco2lcov\fP was run in. .TP .B \fB\-c\fP, \fB\-\-classpath\fP, \fB\-\-classfiles\fP \fIpath\fP A directory or \fB\&.jar\fP file containing the class files whose coverage JaCoCo recorded. JaCoCo reads the coverage counts out of the class files, so it cannot write a report without them. Required, unless \fB\-p\fP names them or the default search below finds them. May be specified multiple times. Default: none. .TP .B \fB\-s\fP, \fB\-\-source\-directory\fP, \fB\-\-source\-dir\fP \fIdirectory\fP A root directory of your Java sources \- that is, one of the directories you would pass to \fBjavac\fP, such that the name of a package, used as a directory path, names the directory holding that package’s sources. Required, unless \fB\-p\fP names them or the default search below finds them. May be specified multiple times. Default: none. .TP .B \fB\-p\fP, \fB\-\-plugin\-directory\fP, \fB\-\-plugin\-dir\fP \fIdirectory\fP Optional. The root of an Eclipse/Maven plugin, or the parent directory of several of them, to be searched for source and class directories in the usual places (\fBsrc\fP, \fBsrc/java\fP, \fBsrc/main/java\fP, \fBsrc/test/java\fP and \fBbin\fP, \fBclasses\fP, \fBtarget/classes\fP). This is a shorthand for the \fB\-s\fP and \fB\-c\fP options which such a directory implies. May be specified multiple times. Default: with none of \fB\-s\fP, \fB\-c\fP and \fB\-p\fP given, the current directory is searched as \fB\-p .\fP would search it \- see \fBWhat JaCoCo needs to be told\fP above. .TP .B \fB\-\-jar\fP \fIjacococli.jar\fP Optional if the environment names the jar, required if it does not. Path to the JaCoCo command line jar. Default: the jar named by the \fBJACOCOCLI_JAR\fP environment variable, else the one found under the directory named by \fBJACOCO_HOME\fP\&. .TP .B \fB\-\-java\fP \fIexecutable\fP Optional. The \fBjava\fP executable used to run the JaCoCo command line jar. Default: \fB$JAVA_HOME/bin/java\fP if that is an executable, else \fBjava\fP, found on your PATH. .TP .B \fB\-\-xml\fP \fIfile\fP Optional. Write the intermediate JaCoCo XML report to the named file and keep it. Default: a temporary file, removed when \fBjacoco2lcov\fP exits. .TP .B \fB\-\-xml2lcov\fP \fIpath\fP Optional. The \fBxml2lcov\fP executable to use. Default: the one installed next to \fBjacoco2lcov\fP\&. On Windows, a wrapper which Windows can run \- an \fBxml2lcov.bat\fP, say \- is preferred to the extensionless script beside it. .TP .B \fB\-v\fP, \fB\-\-verbose\fP Optional. Print each command before it is run. Default: off \- only warnings, errors and notices are printed. .TP .B \fB\-k\fP, \fB\-\-keep\-going\fP Optional. Ignore errors and continue processing. Default: off \- stop at the first error. .TP .B \fB\-h\fP, \fB\-\-help\fP Print usage information and exit. .UNINDENT .sp \fBCommon options\fP .sp Every other option \fBjacoco2lcov\fP accepts is one the rest of the suite accepts, and means here what it means there \- it is applied to the translated data: .INDENT 0.0 .INDENT 3.5 .sp .EX $ jacoco2lcov \-o mydata.info \-s src \-c bin \-\-exclude=\(aq*/test/*\(aq \e \-\-filter branch mytest.exec .EE .UNINDENT .UNINDENT .sp See \fBlcov(1) \%\fP and \fBlcovrc(5) \%\fP for details of these options and of the configuration settings which also reach them. .SH EXAMPLES .INDENT 0.0 .INDENT 3.5 .sp .EX # run your tests with the JaCoCo agent attached, to collect coverage $ java \-javaagent:jacocoagent.jar=destfile=test1.exec \-cp bin MyTest1 $ java \-javaagent:jacocoagent.jar=destfile=test2.exec \-cp bin MyTest2 # translate all of the execution data in one step $ jacoco2lcov \-o mydata.info \-s src \-c bin test1.exec test2.exec # the same, run from the root of a conventionally laid out project: with # no directory named, the ones the layout implies are used $ jacoco2lcov \-o mydata.info test1.exec test2.exec # the same, for a directory of Eclipse/Maven plugins, keeping the # intermediate XML report and dropping the test sources from the result $ jacoco2lcov \-o mydata.info \-p plugins \-\-xml jacoco.xml \e \-\-exclude \(aq*/src/test/java/*\(aq test1.exec test2.exec # a build which wrote one .exec file per test below a results directory, # translated from the directory the rest of your coverage data is # relative to: naming that directory is what makes the file names in the # result line up with it $ jacoco2lcov \-d /work/myproject \-o mydata.info \-p plugins results # and generate an HTML coverage report. JaCoCo reports lines as covered # whose branches it never saw evaluated, which genhtml considers # inconsistent \- see \(aqConsistency\(aq above $ genhtml \-o html_report mydata.info \-\-branch\-coverage \e \-\-ignore\-errors inconsistent .EE .UNINDENT .UNINDENT .SH ENVIRONMENT .INDENT 0.0 .TP .B \fBJACOCOCLI_JAR\fP The JaCoCo command line jar to run, if \fB\-\-jar\fP does not name one. .TP .B \fBJACOCO_HOME\fP The root of a JaCoCo installation, searched for \fBlib/jacococli.jar\fP and then \fBjacococli.jar\fP if neither \fB\-\-jar\fP nor \fBJACOCOCLI_JAR\fP names a jar. .TP .B \fBJAVA_HOME\fP The root of the Java installation whose \fBbin/java\fP is used to run the JaCoCo command line jar, if \fB\-\-java\fP does not name one. .UNINDENT .SH AUTHOR .sp Henry Cox <\%> .SH SEE ALSO .sp \fBlcov(1) \%\fP, \fBgenhtml(1) \%\fP, \fBxml2lcov(1) \%\fP .INDENT 0.0 .IP \(bu 2 JaCoCo documentation: \% .IP \(bu 2 JaCoCo command line interface: \% .UNINDENT .SH Copyright 2024-2026, LCOV Project .\" End of generated man page.