.\" Automatically generated by Pandoc 3.1.11.1 .\" .TH "uncov" "1" "January 20, 2024" "uncov v0.5" "" .SH NAME uncov is a software development tool that collect and processes coverage reports. .PP \f[B]NOTE:\f[R] since uncov\-gcov isn\[cq]t the only way to collect C and C++ coverage for uncov anymore, it is deprecated. However, it is still provided in case it might be useful in some environments. Using \[lq]uncov new\-gcovi\[rq] should work noticeably faster and doesn\[cq]t require sources on adding build to the database. .SH SYNOPSIS \f[B]uncov\f[R] \f[B]\-h|\-\-help\f[R] .PP \f[B]uncov\f[R] \f[B]\-v|\-\-version\f[R] .PP \f[B]uncov\f[R] \f[B][<repo\-path>]\f[R] \f[B]<subcommand>\f[R] \f[B][<subcommand args>\&...]\f[R] .SH OPTIONS .SS \f[B]\-\-help, \-h\f[R] Displays short usage help. .SS \f[B]\-\-version, \-v\f[R] Displays version information. .SH DESCRIPTION \f[CR]uncov\f[R] operates a number of entities, which are directly linked to subcommands and information they output. Below you can find their description. .SS Repository Repository is used as a source of file contents and its root directory (not worktree one) is used to store data of \f[CR]uncov\f[R] itself. While the relation by default is of one\-to\-one kind, same \f[CR]uncov\f[R] data can be shared by multiple copies of the same repository by linking or copying \f[CR]uncov.sqlite\f[R] file manually. .PP Repository that corresponds to current working directory is discovered automatically and doesn\[cq]t need to be specified explicitly. Otherwise \f[B]<repo\-path>\f[R] can point either to repository directory (\f[CR].git\f[R]) or its main worktree (doesn\[cq]t seem to work with secondary worktrees). .SS Builds The largest entity \f[CR]uncov\f[R] operates within repository is a build. A build has the following properties: .IP \[bu] 2 number identifying the build (greater than \f[CR]0\f[R]); .IP \[bu] 2 name of reference within repository (branch usually); .IP \[bu] 2 commit object that corresponds to the build; .IP \[bu] 2 date and time at which it was imported; .IP \[bu] 2 finally, set of files with their coverage that constitute a build. .SS Files File is the second most important thing after a build. It\[cq]s characterised by: .IP \[bu] 2 path within repository; .IP \[bu] 2 coverage information (basically an array specifying which lines are covered); .IP \[bu] 2 MD5 hash (to verify that \f[CR]uncov\f[R] state is consistent with repository). .SS Directories As we have set of files with their paths, we can derive interesting part of file\-system structure of repository (ignoring the rest of it, where there are no source files). Directory is just a sum of information of all files it contains. .SS Build relation In order to be able to calculate change of coverage an ordering of builds is imposed, which currently simply assumes that for build number \f[CR]N\f[R] there is a \f[I]previous build\f[R] with number \f[CR]N \- 1\f[R] (when \f[CR]N > 0\f[R], build number \f[CR]0\f[R] has no previous build). .SS Statistics File coverage information is the sole source of statistics. Based on data provided any line of code is classified as either \f[I]relevant\f[R] or \f[I]not relevant\f[R]. Relevant lines in turn can be \f[I]covered\f[R] or \f[I]missed\f[R]. So each source line must be in one of three states: .IP \[bu] 2 not relevant; .IP \[bu] 2 not covered (with number of hits being \f[CR]0\f[R]); .IP \[bu] 2 covered (with number of hits being greater than \f[CR]0\f[R]). .PP Coverage rate is defined simply as number of covered lines divided by number of relevant lines. If file consists solely of not relevant lines (which is also the case for files that don\[cq]t exist in one of builds being compared), it\[cq]s assumed to have 100% coverage. We also have number of lines covered, missed and total number of relevant lines (sum of previous two) and can calculate their changes. .PP It is these statistics that are displayed by subcommands alongside builds, directories and files. Data describing changes is calculated from state of files in two builds: some build and build that is considered to be its predecessor. .SS Comparison Comparison accounts for hierarchy: build comparison compares all their files, directory comparison compares files under specified path, file comparison compares only one file. .PP However, comparing coverage is not exactly the same as comparing files. While we are interested in whether changed code is covered we don\[cq]t really care about addition or removal of lines that aren\[cq]t relevant for coverage. So these uninteresting changes are not shown. .PP On the other hand, change of coverage when only number of line hits increased or decreased is also irrelevant in most cases and are shown only by separate command. Regular comparison draws attention mainly to lines that have changed their state (e.g., from \[lq]not covered\[rq] to \[lq]covered\[rq] or vice versa). Should such lines be part of diff context, they are displayed as somewhat dimmed compared to lines with interesting changes. .SS Notations For the sake of brevity interface uses several intuitive abbreviations: .IP \[bu] 2 Cov \[en] coverage; .IP \[bu] 2 Ref \[en] reference (of VCS); .IP \[bu] 2 C \[en] covered; .IP \[bu] 2 M \[en] missed; .IP \[bu] 2 R \[en] relevant. .SH SUBCOMMANDS .SS Syntax of build numbers Build numbers are specified in arguments for subcommands by being prepended with \f[CR]\[at]\f[R] sign. So to refer to build number \f[CR]5\f[R], one would write \f[CR]\[at]5\f[R]. .PP Build numbers start at \f[CR]1\f[R], this leaves \f[CR]\[at]0\f[R] unused. It is thus repurposed to be a handy shortcut for the latest build. An alternative form of writing \f[CR]\[at]0\f[R] is \f[CR]\[at]\[at]\f[R]. .PP Build numbers can also be specified in the form of \f[CR]\[at]\-N\f[R], in which case they select Nth to the latest build. For example, to specify range from previous build to one build before that one would write \f[CR]\[at]\-1 \[at]\-2\f[R]. .PP Lastly, branch names can be used to specify latest build from that branch (e.g., \f[CR]\[at]master\f[R]). .SS Resolving ambiguity Some commands can take optional build number, which opens the door for ambiguity between file/directory names and build identifiers. Anything that starts with \f[CR]\[at]\f[R] at a suitable position on command\-line is assumed to be build number. For files which have \f[CR]\[at]\f[R] as prefix, specifying build number becomes mandatory. As an example: .IP .EX # this doesn\[aq]t work uncov show \[at]strangely\-named\-file # this is equivalent and works uncov show \[at]\[at] \[at]strangely\-named\-file .EE .SS Default build If a subcommand accepts build number, in almost all cases it\[cq]s an optional parameter and latest build is used when this argument is omitted. .SS Subcommand aliases Instead of requiring arguments for subcommands a different approach has been taken. Some commands have several names and depending on how you call them, they act slightly differently. .SS Paths As a convenience when current working directory is under work tree of a repository, paths that do not start with a slash \f[CR]/\f[R] are automatically converted to be relative to root of the repository. .SH LIST OF SUBCOMMANDS .SS build Displays information about single build. .PP \f[B]Usage: build\f[R] .PP Describes the last build. .PP \f[B]Usage: build <build>\f[R] .PP Describes \f[B]<build>\f[R]. .SS builds Lists builds. .PP \f[B]Usage: builds\f[R] .PP Lists at most 10 most recent builds. .PP \f[B]Usage: builds <max list length>\f[R] .PP Lists at most \f[B]<max list length>\f[R] most recent builds. .PP \f[B]Usage: builds all\f[R] .PP Lists all builds. .SS changed Same as \f[B]files\f[R] subcommand, but omits listing files which have their coverage rate unchanged. .PP See description of \f[B]files\f[R] subcommand below for syntax. .SS diff Compares builds, directories or files. Lines of files are compared by their state (i.e., changes in number of hits when both old and new values are bigger than \f[CR]0\f[R] are treated as no change). .PP \f[B]Usage: diff\f[R] .PP Compares the last build with its predecessor. .PP \f[B]Usage: diff <old build>\f[R] .PP Compares the last build with \f[B]<old build>\f[R]. .PP \f[B]Usage: diff <old build> <new build>\f[R] .PP Compares \f[B]<new build>\f[R] with \f[B]<old build>\f[R]. .PP \f[B]Usage: diff [<old build>] [<new build>] <path>\f[R] .PP See forms above for information about first two arguments. If \f[B]<path>\f[R] specifies directory in either of two builds, only files under it and below are compared. If \f[B]<path>\f[R] specifies file, only that file is compared. .SS diff\-hits Same as \f[B]diff\f[R] subcommand, but considers change of number of hits of a line to be significant change. .PP See description of \f[B]diff\f[R] subcommand above for syntax. .SS dirs Lists statistics of files grouped by directories they\[cq]re located in. .PP \f[B]Usage: dirs\f[R] .PP Lists all directories of the last build. .PP \f[B]Usage: dirs <build>\f[R] .PP Lists all directories of \f[B]<build>\f[R] comparing them against directories in its predecessor. .PP \f[B]Usage: dirs <old build> <new build>\f[R] .PP Lists all directories of \f[B]<new build>\f[R] comparing them against directories in \f[B]<old build>\f[R]. .PP \f[B]Usage: dirs [<build>] <directory path>\f[R] .PP Lists directories of \f[B]<build>\f[R] (or last build) located under \f[B]<directory path>\f[R]. .PP \f[B]Usage: dirs [<old build>] [<new build>] <directory path>\f[R] .PP See forms above for information about first two arguments. Lists directories located under \f[B]<directory path>\f[R]. .SS files Lists statistics about files. .PP \f[B]Usage: files\f[R] .PP Lists all files of the last build. .PP \f[B]Usage: files <build>\f[R] .PP Lists all files of \f[B]<build>\f[R] comparing them against files in its predecessor. .PP \f[B]Usage: files <old build> <new build>\f[R] .PP Lists all files of \f[B]<new build>\f[R] comparing them against files in \f[B]<old build>\f[R]. .PP \f[B]Usage: files [<build>] <directory path>\f[R] .PP Lists files of \f[B]<build>\f[R] (or last build) located under \f[B]<directory path>\f[R]. .PP \f[B]Usage: files [<old build>] [<new build>] <path>\f[R] .PP See forms above for information about first two arguments. Lists files located under \f[B]<path>\f[R] (if it\[cq]s a directory) or single file that exactly matches the path. .SS get Dumps coverage information of a file. .PP \f[B]Usage: get <build> <file path>\f[R] .PP Prints information about the file in this form: .IP .EX <commit> <line1 coverage as integer> <line2 coverage as integer> <line3 coverage as integer> \&... .EE .PP See description of \f[B]new\f[R] subcommand below for meaning of integer values. .SS help Displays help information. .PP \f[B]Usage: help\f[R] .PP Displays generic information about all subcommands. .PP \f[B]Usage: help <subcommand>\f[R] .PP Displays information about a specific subcommand. .SS missed Same as \f[B]show\f[R] subcommand, but folds not relevant and covered lines and thus displays only parts of files that lack coverage. .PP See description of \f[B]show\f[R] subcommand below for syntax. .SS new Imports new build from standard input. .PP \f[B]Usage: new\f[R] .PP Reads coverage information from standard input in the following format: .IP .EX <commit> <ref name> <file name relative to repository root> <MD5 hash of file contents> <number of lines of coverage> <line1 coverage as integer> <line2 coverage as integer> ... <all other files in the same format> .EE .PP Integers have the following meaning: .IP \[bu] 2 when less than zero (specifically \f[CR]\-1\f[R]) \[en] line is not relevant; .IP \[bu] 2 when equal to zero \[en] line is not covered (missed); .IP \[bu] 2 when greater than zero \[en] line is covered and was hit that many times. .SS new\-gcovi Generates coverage via \f[CR]gcov\f[R] and imports it. .PP \f[B]Usage: new\-gcovi [options\&...] [covoutroot]\f[R] .PP \f[B]Parameters:\f[R] .IP \[bu] 2 \f[B]covoutroot\f[R] \[en] where to look for generated coverage data. .PP \f[B]Options:\f[R] .IP \[bu] 2 \f[B]\-h [ \-\-help ]\f[R] \[en] display help message; .IP \[bu] 2 \f[B]\-v [ \-\-verbose ]\f[R] \[en] print output of external commands; .IP \[bu] 2 \f[B]\-e [ \-\-exclude ] arg\f[R] \[en] specifies a path to exclude (can be repeated), paths are taken to be relative to the root of the repository; .IP \[bu] 2 \f[B]\-\-prefix arg\f[R] \[en] prefix to be added to relative path of sources; .IP \[bu] 2 \f[B]\-\-ref\-name arg\f[R] \[en] forces custom ref name; .IP \[bu] 2 \f[B]\-c [ \-\-capture\-worktree ]\f[R] \[en] make a dangling commit if working directory is dirty. .PP To do its work this subcommand invokes \f[CR]gcov\f[R] and then parses its output in intermediate format, which is only mostly stable so usage with some versions of \f[CR]gcov\f[R] might require changes. .SS new\-json Imports new build in JSON format from standard input. .PP \f[B]Usage: new\-json\f[R] .PP Reads coverage information from standard input in the following format: .IP .EX <prefix that doesn\[aq]t contain { character> { \[dq]source_files\[dq]: [ { \[dq]source_digest\[dq]: \[dq]<MD5 hash>\[dq], \[dq]source\[dq]: \[dq]<source, which can be used instead of source_digest>\[dq], \[dq]name\[dq]: \[dq]file name relative to repository root\[dq], \[dq]coverage\[dq]: [null for not relevant lines, int for number of hits] } ... ], \[dq]git\[dq]: { \[dq]head\[dq]: { \[dq]id\[dq]: \[dq]<commit>\[dq] }, \[dq]branch\[dq]: \[dq]<branch>\[dq] } } .EE .PP Any other elements are ignored. .SS regress Same as \f[B]diff\f[R] subcommand, but displays introduced lines that aren\[cq]t covered. .PP See description of \f[B]diff\f[R] subcommand above for syntax. .SS show Prints whole build, files under directory or a single file with coverage information. .PP \f[B]Usage: show\f[R] .PP Prints all files of the last build. .PP \f[B]Usage: show <build>\f[R] .PP Prints all files of \f[B]<build>\f[R]. .PP \f[B]Usage: show <build> <path>\f[R] .PP Prints files of \f[B]<build>\f[R] (or last build) located under \f[B]<path>\f[R] if it specifies directory or one specific file. .SH CONFIGURATION .SS Location and format Configuration is read from \f[B]<repository\-directory>/uncov.ini\f[R] file. If it doesn\[cq]t exist or contains invalid data (e.g., duplicated keys), default settings remain intact. .PP The file has regular ini\-format and can contain either comments that start with \f[B];\f[R] or key\-value pairs like \f[B]tab\-size = 2\f[R] (with or without spaces). .PP Values are interpreted according to types of their keys. Keys with values that are not convertible to corresponding types are ignored. .SS Available settings Format of each entry below: .IP .EX <option> (<type>, [app:] <default value>) <description> .EE .PP \f[B]low\-bound\f[R] (floating point, 70) .PP Percentage boundary between low and medium coverage levels. Normalized to be in the [0, 100] range. If \f[B]low\-bound > hi\-bound\f[R], their values are swapped. .PP \f[B]hi\-bound\f[R] (floating point, 90) .PP Percentage boundary between medium and high coverage levels. Normalized to be in the [0, 100] range. If \f[B]low\-bound > hi\-bound\f[R], their values are swapped. .PP \f[B]tab\-size\f[R] (integer, 4) .PP Width of tabulation in spaces. .PP \f[B]min\-fold\-size\f[R] (integer, \f[B]uncov\f[R]: 3, \f[B]uncov\-web\f[R]: 4) .PP Minimal number of lines to be folded. .PP \f[B]fold\-context\f[R] (integer, 1) .PP Number of visible lines above and below changes. .PP \f[B]diff\-show\-lineno\f[R] (boolean, \f[B]uncov\f[R]: false, \f[B]uncov\-web\f[R]: true) .PP Whether line numbers are displayed in diffs. .SH FILES \f[B]<data\-directory>\f[R] in the following is either git\-directory for a worktree (see \f[B]git\-worktree\f[R](1)) or for the repository that owns it, whichever has either of those files when checking directories in the order they are mentioned. If no files found, repository\[cq]s git\-directory is used. .PP \f[B]<data\-directory>/uncov.sqlite\f[R] \[en] storage of coverage data. .PP \f[B]<data\-directory>/uncov.ini\f[R] \[en] configuration. .SH SEE ALSO \f[B]uncov\-gcov\f[R](1), \f[B]uncov\-web\f[R](1) .SH AUTHORS xaizek <xaizek@posteo.net>.