xaizek / uncov (License: AGPLv3+) (since 2018-12-07)
Uncov(er) is a tool that collects and processes code coverage reports.
<root> / docs / uncov.1 (a2b01d7897b5407cd6922721fd650915523b00e9) (16KiB) (mode 100644) [raw]
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498
.\" 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>.
Hints

Before first commit, do not forget to setup your git environment:
git config --global user.name "your_name_here"
git config --global user.email "your@email_here"

Clone this repository using HTTP(S):
git clone https://code.reversed.top/user/xaizek/uncov

Clone this repository using ssh (do not forget to upload a key first):
git clone ssh://rocketgit@code.reversed.top/user/xaizek/uncov

You are allowed to anonymously push to this repository.
This means that your pushed commits will automatically be transformed into a pull request:
... clone the repository ...
... make some changes and some commits ...
git push origin master