xaizek / uncov (License: AGPLv3+) (since 2018-12-07)
Uncov(er) is a tool that collects and processes code coverage reports.
Clone URLs: https://code.reversed.top/user/xaizek/uncov ssh://rocketgit@code.reversed.top/user/xaizek/uncov
v0.1 v0.2 v0.3 v0.4 v0.5 master
Commit 103f07e0db891c06671edb14a2a2177db950709a

Re-generate manuals with newer pandoc version
Author: xaizek
Author date (UTC): 2024-01-20 14:28
Committer name: xaizek
Committer date (UTC): 2024-01-20 14:28
Parent(s): 84366ab858f2d63874fbbe141702fd79c14e91b9
Signing key: 99DC5E4DB05F6BE2
Tree: 38370cad754fdd6fa48ff6512fc37ac775cecf1e
File Lines added Lines deleted
docs/uncov-gcov.1 46 89
docs/uncov-web.1 23 50
docs/uncov.1 91 150
File docs/uncov-gcov.1 changed (mode: 100644) (index efa921c..da815ea)
1 .\" Automatically generated by Pandoc 2.17.1.1
1 .\" Automatically generated by Pandoc 3.1.11.1
2 2 .\" .\"
3 .\" Define V font for inline verbatim, using C font in formats
4 .\" that render this, and otherwise B font.
5 .ie "\f[CB]x\f[]"x" \{\
6 . ftr V B
7 . ftr VI BI
8 . ftr VB B
9 . ftr VBI BI
10 .\}
11 .el \{\
12 . ftr V CR
13 . ftr VI CI
14 . ftr VB CB
15 . ftr VBI CBI
16 .\}
17 .TH "uncov-gcov" "1" "November 18, 2022" "uncov v0.5" ""
18 .hy
3 .TH "uncov-gcov" "1" "January 20, 2024" "uncov v0.5" ""
19 4 .SH NAME .SH NAME
20 .PP
21 uncov-gcov is coverage information collector for C and C++ languages
5 uncov\-gcov is coverage information collector for C and C++ languages
22 6 that can be used with \f[B]uncov(1)\f[R]. that can be used with \f[B]uncov(1)\f[R].
23 7 .PP .PP
24 \f[B]NOTE:\f[R] since uncov-gcov isn\[cq]t the only way to collect C and
25 C++ coverage for uncov anymore, its use is discouraged.
8 \f[B]NOTE:\f[R] since uncov\-gcov isn\[cq]t the only way to collect C
9 and C++ coverage for uncov anymore, its use is discouraged.
26 10 It is provided in case it might work better in some contexts because of It is provided in case it might work better in some contexts because of
27 11 some unique options (like taking exclusion markers of LCOV into some unique options (like taking exclusion markers of LCOV into
28 12 account). account).
29 It might be a good idea to switch to using \[lq]uncov new-gcovi\[rq]
13 It might be a good idea to switch to using \[lq]uncov new\-gcovi\[rq]
30 14 subcommand. subcommand.
31 15 .SH SYNOPSIS .SH SYNOPSIS
16 \f[B]uncov\-gcov\f[R] \f[B]\-h|\-\-help\f[R]
32 17 .PP .PP
33 \f[B]uncov-gcov\f[R] \f[B]-h|--help\f[R]
34 .PP
35 \f[B]uncov-gcov\f[R] \f[B]-v|--version\f[R]
18 \f[B]uncov\-gcov\f[R] \f[B]\-v|\-\-version\f[R]
36 19 .PP .PP
37 \f[B]uncov-gcov\f[R] \f[B][<options>\&...]\f[R]
20 \f[B]uncov\-gcov\f[R] \f[B][<options>\&...]\f[R]
38 21 .SH OPTIONS .SH OPTIONS
39 .SS \f[B]--help, -h\f[R]
40 .PP
22 .SS \f[B]\-\-help, \-h\f[R]
41 23 Displays short usage help. Displays short usage help.
42 .SS \f[B]--version, -v\f[R]
43 .PP
24 .SS \f[B]\-\-version, \-v\f[R]
44 25 Displays version information. Displays version information.
45 .SS \f[B]--verbose\f[R]
46 .PP
26 .SS \f[B]\-\-verbose\f[R]
47 27 Print verbose messages. Print verbose messages.
48 .SS \f[B]--dryrun\f[R]
49 .PP
28 .SS \f[B]\-\-dryrun\f[R]
50 29 Run the script without printing report. Run the script without printing report.
51 .SS \f[B]--gcov\f[R] [=gcov]
52 .PP
30 .SS \f[B]\-\-gcov\f[R] [=gcov]
53 31 Set the location of gcov. Set the location of gcov.
54 .SS \f[B]--gcov-options\f[R] [=\[lq]\[rq]]
55 .PP
32 .SS \f[B]\-\-gcov\-options\f[R] [=\[lq]\[rq]]
56 33 Set the options given to gcov. Set the options given to gcov.
57 .SS \f[B]-r\f[R], \f[B]--root\f[R] [=.]
58 .PP
34 .SS \f[B]\-r\f[R], \f[B]\-\-root\f[R] [=.]
59 35 Set the root directory. Set the root directory.
60 .SS \f[B]-b\f[R], \f[B]--build-root\f[R] [={discovered}]
61 .PP
36 .SS \f[B]\-b\f[R], \f[B]\-\-build\-root\f[R] [={discovered}]
62 37 Set the directory from which gcov will be called; by default gcov is run Set the directory from which gcov will be called; by default gcov is run
63 38 in the directory of the .o files; however the paths of the sources are in the directory of the .o files; however the paths of the sources are
64 39 often relative to the directory from which the compiler was run and often relative to the directory from which the compiler was run and
65 40 these relative paths are saved in the .o file; when this happens, gcov these relative paths are saved in the .o file; when this happens, gcov
66 41 needs to run in the same directory as the compiler in order to find the needs to run in the same directory as the compiler in order to find the
67 42 source files. source files.
68 .SS \f[B]--collect-root\f[R] [={value of --root}]
69 .PP
43 .SS \f[B]\-\-collect\-root\f[R] [={value of \-\-root}]
70 44 Directory to look gcov files in. Directory to look gcov files in.
71 .SS \f[B]-e\f[R], \f[B]--exclude\f[R] [=\[lq]\[rq]]
72 .PP
45 .SS \f[B]\-e\f[R], \f[B]\-\-exclude\f[R] [=\[lq]\[rq]]
73 46 List of paths to exclude. List of paths to exclude.
74 47 Can be specifieid multiple times. Can be specifieid multiple times.
75 48 .PP .PP
76 49 Examples: Examples:
77 50 .IP .IP
78 .nf
79 \f[C]
80 uncov-gcov -\[rs]-exclude build-release -\[rs]-exclude build-debug ...
81 uncov-gcov -\[rs]-exclude build-release build-debug ...
82 uncov-gcov -\[rs]-exclude build* ...
83 \f[R]
84 .fi
85 .SS \f[B]-i\f[R], \f[B]--include\f[R] [=\[lq]\[rq]]
86 .PP
51 .EX
52 uncov\-gcov \-\[rs]\-exclude build\-release \-\[rs]\-exclude build\-debug ...
53 uncov\-gcov \-\[rs]\-exclude build\-release build\-debug ...
54 uncov\-gcov \-\[rs]\-exclude build* ...
55 .EE
56 .SS \f[B]\-i\f[R], \f[B]\-\-include\f[R] [=\[lq]\[rq]]
87 57 List of paths to include. List of paths to include.
88 58 Can be specifieid multiple times. Can be specifieid multiple times.
89 See \f[B]--exclude\f[R] for examples.
90 .SS \f[B]-E\f[R], \f[B]--exclude-pattern\f[R] [=\[lq]\[rq]]
91 .PP
59 See \f[B]\-\-exclude\f[R] for examples.
60 .SS \f[B]\-E\f[R], \f[B]\-\-exclude\-pattern\f[R] [=\[lq]\[rq]]
92 61 Set exclude file/directory pattern. Set exclude file/directory pattern.
93 .SS \f[B]-x\f[R], \f[B]--extension\f[R] [=.h,.hh,.hpp,.hxx,.c,.cc,.cpp,.cxx,.m,.mm]
94 .PP
62 .SS \f[B]\-x\f[R], \f[B]\-\-extension\f[R] [=.h,.hh,.hpp,.hxx,.c,.cc,.cpp,.cxx,.m,.mm]
95 63 Set extension of files to process. Set extension of files to process.
96 .SS \f[B]-n\f[R], \f[B]--no-gcov\f[R]
97 .PP
64 .SS \f[B]\-n\f[R], \f[B]\-\-no\-gcov\f[R]
98 65 Do not run gcov. Do not run gcov.
99 .SS \f[B]--encodings\f[R] [=utf-8,latin-1]
100 .PP
66 .SS \f[B]\-\-encodings\f[R] [=utf\-8,latin\-1]
101 67 Source encodings to try in order of preference. Source encodings to try in order of preference.
102 .SS \f[B]--dump\f[R] <file>
103 .PP
68 .SS \f[B]\-\-dump\f[R] <file>
104 69 Dump JSON payload to a file. Dump JSON payload to a file.
105 .SS \f[B]--follow-symlinks\f[R]
106 .PP
70 .SS \f[B]\-\-follow\-symlinks\f[R]
107 71 Follow symlinks. Follow symlinks.
108 .SS \f[B]-c\f[R], \f[B]--capture-worktree\f[R]
109 .PP
72 .SS \f[B]\-c\f[R], \f[B]\-\-capture\-worktree\f[R]
110 73 Make a dangling commit if working directory is dirty. Make a dangling commit if working directory is dirty.
111 .SS \f[B]--ref-name\f[R] [={discovered}]
112 .PP
74 .SS \f[B]\-\-ref\-name\f[R] [={discovered}]
113 75 Force custom ref name. Force custom ref name.
114 .SS \f[B]--cpp-dtor-invocations\f[R]
115 .PP
76 .SS \f[B]\-\-cpp\-dtor\-invocations\f[R]
116 77 Count coverage for C++ destructor invocations, which tends to show up at Count coverage for C++ destructor invocations, which tends to show up at
117 lines that have the closing brace (\f[V]{\f[R]).
78 lines that have the closing brace (\f[CR]{\f[R]).
118 79 .SH USAGE .SH USAGE
119 .PP
120 uncov-gcov can be used to generate coverage, but it seems to not play
121 well with out-of-tree builds (some coverage is missing, this issue is
80 uncov\-gcov can be used to generate coverage, but it seems to not play
81 well with out\-of\-tree builds (some coverage is missing, this issue is
122 82 inherited from its origin), so the recommended way of recording coverage inherited from its origin), so the recommended way of recording coverage
123 83 information is as follows: information is as follows:
124 84 .IP .IP
125 .nf
126 \f[C]
85 .EX
127 86 # reset coverage counters from previous runs # reset coverage counters from previous runs
128 find . -name \[aq]*.gcda\[aq] -delete
87 find . \-name \[aq]*.gcda\[aq] \-delete
129 88
130 89 # run tests here with something like \[ga]make check\[ga] # run tests here with something like \[ga]make check\[ga]
131 90
132 91 # generage coverage for every object file found (change \[dq].\[dq] to build root) # generage coverage for every object file found (change \[dq].\[dq] to build root)
133 find . -name \[aq]*.o\[aq] -exec gcov -p {} +
92 find . \-name \[aq]*.o\[aq] \-exec gcov \-p {} +
134 93
135 # generage and combine coverage reports (-\[rs]-capture-worktree automatically
94 # generage and combine coverage reports (\-\[rs]\-capture\-worktree automatically
136 95 # makes stray commit if repository is dirty) # makes stray commit if repository is dirty)
137 uncov-gcov -\[rs]-root . -\[rs]-no-gcov -\[rs]-capture-worktree -\[rs]-exclude tests | uncov new
96 uncov\-gcov \-\[rs]\-root . \-\[rs]\-no\-gcov \-\[rs]\-capture\-worktree \-\[rs]\-exclude tests | uncov new
138 97
139 98 # remove coverage reports # remove coverage reports
140 find . -name \[aq]*.gcov\[aq] -delete
141 \f[R]
142 .fi
99 find . \-name \[aq]*.gcov\[aq] \-delete
100 .EE
143 101 .PP .PP
144 102 These commands can be put in a separate script or embedded directly into These commands can be put in a separate script or embedded directly into
145 103 build system. build system.
146 104 .SH SEE ALSO .SH SEE ALSO
147 .PP
148 \f[B]uncov\f[R](1), \f[B]uncov-web\f[R](1)
105 \f[B]uncov\f[R](1), \f[B]uncov\-web\f[R](1)
149 106 .SH AUTHORS .SH AUTHORS
150 107 xaizek <xaizek@posteo.net>. xaizek <xaizek@posteo.net>.
File docs/uncov-web.1 changed (mode: 100644) (index bbe8d29..2c30223)
1 .\" Automatically generated by Pandoc 2.17.1.1
1 .\" Automatically generated by Pandoc 3.1.11.1
2 2 .\" .\"
3 .\" Define V font for inline verbatim, using C font in formats
4 .\" that render this, and otherwise B font.
5 .ie "\f[CB]x\f[]"x" \{\
6 . ftr V B
7 . ftr VI BI
8 . ftr VB B
9 . ftr VBI BI
10 .\}
11 .el \{\
12 . ftr V CR
13 . ftr VI CI
14 . ftr VB CB
15 . ftr VBI CBI
16 .\}
17 .TH "uncov-web" "1" "November 18, 2022" "uncov v0.5" ""
18 .hy
3 .TH "uncov-web" "1" "January 20, 2024" "uncov v0.5" ""
19 4 .SH NAME .SH NAME
20 .PP
21 uncov-web is a HTTP-server that provides Web-UI for browsing coverage
5 uncov\-web is a HTTP\-server that provides Web\-UI for browsing coverage
22 6 information collected by \f[B]uncov(1)\f[R]. information collected by \f[B]uncov(1)\f[R].
23 7 .SH SYNOPSIS .SH SYNOPSIS
8 \f[B]uncov\-web\f[R] \f[B]\-h|\-\-help\f[R]
24 9 .PP .PP
25 \f[B]uncov-web\f[R] \f[B]-h|--help\f[R]
26 .PP
27 \f[B]uncov-web\f[R] \f[B]-v|--version\f[R]
10 \f[B]uncov\-web\f[R] \f[B]\-v|\-\-version\f[R]
28 11 .PP .PP
29 \f[B]uncov-web\f[R] \f[B]--vhost\f[R] <host-name> \f[B]--ip\f[R]
30 [=0.0.0.0] \f[B]--repo\f[R] [=.]
31 \f[B]--port\f[R] [=8000]
12 \f[B]uncov\-web\f[R] \f[B]\-\-vhost\f[R] <host\-name> \f[B]\-\-ip\f[R]
13 [=0.0.0.0] \f[B]\-\-repo\f[R] [=.]
14 \f[B]\-\-port\f[R] [=8000]
32 15 .SH OPTIONS .SH OPTIONS
33 .SS \f[B]--help, -h\f[R]
34 .PP
16 .SS \f[B]\-\-help, \-h\f[R]
35 17 Displays short usage help. Displays short usage help.
36 .SS \f[B]--version, -v\f[R]
37 .PP
18 .SS \f[B]\-\-version, \-v\f[R]
38 19 Displays version information. Displays version information.
39 .SS \f[B]--vhost\f[R] <host-name>
40 .PP
20 .SS \f[B]\-\-vhost\f[R] <host\-name>
41 21 Sets virtual host name. Sets virtual host name.
42 22 This option is mandatory. This option is mandatory.
43 .SS \f[B]--ip\f[R] [=0.0.0.0]
44 .PP
23 .SS \f[B]\-\-ip\f[R] [=0.0.0.0]
45 24 IP address to bind to. IP address to bind to.
46 25 The default is to bind to all interfaces. The default is to bind to all interfaces.
47 .SS \f[B]--repo\f[R] [=.]
48 .PP
26 .SS \f[B]\-\-repo\f[R] [=.]
49 27 Path to repository. Path to repository.
50 .SS \f[B]--port\f[R] [=8000]
51 .PP
28 .SS \f[B]\-\-port\f[R] [=8000]
52 29 Post to listen on. Post to listen on.
53 30 .SH DESCRIPTION .SH DESCRIPTION
54 .PP
55 Once started provides HTTP-server to view coverage reports.
31 Once started provides HTTP\-server to view coverage reports.
56 32 Does not daemonize itself. Does not daemonize itself.
57 33 .SS Notations .SS Notations
58 .PP
59 34 For the sake of brevity interface uses several intuitive abbreviations: For the sake of brevity interface uses several intuitive abbreviations:
60 35 .IP \[bu] 2 .IP \[bu] 2
61 36 Cov \[en] coverage; Cov \[en] coverage;
 
... ... M \[en] missed;
68 43 .IP \[bu] 2 .IP \[bu] 2
69 44 R \[en] relevant. R \[en] relevant.
70 45 .SH FILES .SH FILES
46 \f[B]<data\-directory>\f[R] in the following is either git\-directory
47 for a worktree (see \f[B]git\-worktree\f[R](1)) or for the repository
48 that owns it, whichever has either of those files when checking
49 directories in the order they are mentioned.
50 If no files found, repository\[cq]s git\-directory is used.
71 51 .PP .PP
72 \f[B]<data-directory>\f[R] in the following is either git-directory for
73 a worktree (see \f[B]git-worktree\f[R](1)) or for the repository that
74 owns it, whichever has either of those files when checking directories
75 in the order they are mentioned.
76 If no files found, repository\[cq]s git-directory is used.
77 .PP
78 \f[B]<data-directory>/uncov.sqlite\f[R] \[en] storage of coverage data.
52 \f[B]<data\-directory>/uncov.sqlite\f[R] \[en] storage of coverage data.
79 53 .PP .PP
80 \f[B]<data-directory>/uncov.ini\f[R] \[en] configuration.
54 \f[B]<data\-directory>/uncov.ini\f[R] \[en] configuration.
81 55 .SH SEE ALSO .SH SEE ALSO
82 .PP
83 \f[B]uncov\f[R](1), \f[B]uncov-gcov\f[R](1)
56 \f[B]uncov\f[R](1), \f[B]uncov\-gcov\f[R](1)
84 57 .SH AUTHORS .SH AUTHORS
85 58 xaizek <xaizek@posteo.net>. xaizek <xaizek@posteo.net>.
File docs/uncov.1 changed (mode: 100644) (index 51755ee..af050cc)
1 .\" Automatically generated by Pandoc 2.17.1.1
1 .\" Automatically generated by Pandoc 3.1.11.1
2 2 .\" .\"
3 .\" Define V font for inline verbatim, using C font in formats
4 .\" that render this, and otherwise B font.
5 .ie "\f[CB]x\f[]"x" \{\
6 . ftr V B
7 . ftr VI BI
8 . ftr VB B
9 . ftr VBI BI
10 .\}
11 .el \{\
12 . ftr V CR
13 . ftr VI CI
14 . ftr VB CB
15 . ftr VBI CBI
16 .\}
17 .TH "uncov" "1" "November 18, 2022" "uncov v0.5" ""
18 .hy
3 .TH "uncov" "1" "January 20, 2024" "uncov v0.5" ""
19 4 .SH NAME .SH NAME
20 .PP
21 5 uncov is a software development tool that collect and processes coverage uncov is a software development tool that collect and processes coverage
22 6 reports. reports.
23 7 .SH SYNOPSIS .SH SYNOPSIS
8 \f[B]uncov\f[R] \f[B]\-h|\-\-help\f[R]
24 9 .PP .PP
25 \f[B]uncov\f[R] \f[B]-h|--help\f[R]
26 .PP
27 \f[B]uncov\f[R] \f[B]-v|--version\f[R]
10 \f[B]uncov\f[R] \f[B]\-v|\-\-version\f[R]
28 11 .PP .PP
29 \f[B]uncov\f[R] \f[B][<repo-path>]\f[R] \f[B]<subcommand>\f[R]
12 \f[B]uncov\f[R] \f[B][<repo\-path>]\f[R] \f[B]<subcommand>\f[R]
30 13 \f[B][<subcommand args>\&...]\f[R] \f[B][<subcommand args>\&...]\f[R]
31 14 .SH OPTIONS .SH OPTIONS
32 .SS \f[B]--help, -h\f[R]
33 .PP
15 .SS \f[B]\-\-help, \-h\f[R]
34 16 Displays short usage help. Displays short usage help.
35 .SS \f[B]--version, -v\f[R]
36 .PP
17 .SS \f[B]\-\-version, \-v\f[R]
37 18 Displays version information. Displays version information.
38 19 .SH DESCRIPTION .SH DESCRIPTION
39 .PP
40 \f[V]uncov\f[R] operates a number of entities, which are directly linked
41 to subcommands and information they output.
20 \f[CR]uncov\f[R] operates a number of entities, which are directly
21 linked to subcommands and information they output.
42 22 Below you can find their description. Below you can find their description.
43 23 .SS Repository .SS Repository
44 .PP
45 24 Repository is used as a source of file contents and its root directory Repository is used as a source of file contents and its root directory
46 (not worktree one) is used to store data of \f[V]uncov\f[R] itself.
47 While the relation by default is of one-to-one kind, same
48 \f[V]uncov\f[R] data can be shared by multiple copies of the same
49 repository by linking or copying \f[V]uncov.sqlite\f[R] file manually.
25 (not worktree one) is used to store data of \f[CR]uncov\f[R] itself.
26 While the relation by default is of one\-to\-one kind, same
27 \f[CR]uncov\f[R] data can be shared by multiple copies of the same
28 repository by linking or copying \f[CR]uncov.sqlite\f[R] file manually.
50 29 .PP .PP
51 30 Repository that corresponds to current working directory is discovered Repository that corresponds to current working directory is discovered
52 31 automatically and doesn\[cq]t need to be specified explicitly. automatically and doesn\[cq]t need to be specified explicitly.
53 Otherwise \f[B]<repo-path>\f[R] can point either to repository directory
54 (\f[V].git\f[R]) or its main worktree (doesn\[cq]t seem to work with
55 secondary worktrees).
32 Otherwise \f[B]<repo\-path>\f[R] can point either to repository
33 directory (\f[CR].git\f[R]) or its main worktree (doesn\[cq]t seem to
34 work with secondary worktrees).
56 35 .SS Builds .SS Builds
57 .PP
58 The largest entity \f[V]uncov\f[R] operates within repository is a
36 The largest entity \f[CR]uncov\f[R] operates within repository is a
59 37 build. build.
60 38 A build has the following properties: A build has the following properties:
61 39 .IP \[bu] 2 .IP \[bu] 2
62 number identifying the build (greater than \f[V]0\f[R]);
40 number identifying the build (greater than \f[CR]0\f[R]);
63 41 .IP \[bu] 2 .IP \[bu] 2
64 42 name of reference within repository (branch usually); name of reference within repository (branch usually);
65 43 .IP \[bu] 2 .IP \[bu] 2
 
... ... date and time at which it was imported;
69 47 .IP \[bu] 2 .IP \[bu] 2
70 48 finally, set of files with their coverage that constitute a build. finally, set of files with their coverage that constitute a build.
71 49 .SS Files .SS Files
72 .PP
73 50 File is the second most important thing after a build. File is the second most important thing after a build.
74 51 It\[cq]s characterised by: It\[cq]s characterised by:
75 52 .IP \[bu] 2 .IP \[bu] 2
 
... ... path within repository;
78 55 coverage information (basically an array specifying which lines are coverage information (basically an array specifying which lines are
79 56 covered); covered);
80 57 .IP \[bu] 2 .IP \[bu] 2
81 MD5 hash (to verify that \f[V]uncov\f[R] state is consistent with
58 MD5 hash (to verify that \f[CR]uncov\f[R] state is consistent with
82 59 repository). repository).
83 60 .SS Directories .SS Directories
84 .PP
85 61 As we have set of files with their paths, we can derive interesting part As we have set of files with their paths, we can derive interesting part
86 of file-system structure of repository (ignoring the rest of it, where
62 of file\-system structure of repository (ignoring the rest of it, where
87 63 there are no source files). there are no source files).
88 64 Directory is just a sum of information of all files it contains. Directory is just a sum of information of all files it contains.
89 65 .SS Build relation .SS Build relation
90 .PP
91 66 In order to be able to calculate change of coverage an ordering of In order to be able to calculate change of coverage an ordering of
92 67 builds is imposed, which currently simply assumes that for build number builds is imposed, which currently simply assumes that for build number
93 \f[V]N\f[R] there is a \f[I]previous build\f[R] with number
94 \f[V]N - 1\f[R] (when \f[V]N > 0\f[R], build number \f[V]0\f[R] has no
95 previous build).
68 \f[CR]N\f[R] there is a \f[I]previous build\f[R] with number
69 \f[CR]N \- 1\f[R] (when \f[CR]N > 0\f[R], build number \f[CR]0\f[R] has
70 no previous build).
96 71 .SS Statistics .SS Statistics
97 .PP
98 72 File coverage information is the sole source of statistics. File coverage information is the sole source of statistics.
99 73 Based on data provided any line of code is classified as either Based on data provided any line of code is classified as either
100 74 \f[I]relevant\f[R] or \f[I]not relevant\f[R]. \f[I]relevant\f[R] or \f[I]not relevant\f[R].
 
... ... So each source line must be in one of three states:
103 77 .IP \[bu] 2 .IP \[bu] 2
104 78 not relevant; not relevant;
105 79 .IP \[bu] 2 .IP \[bu] 2
106 not covered (with number of hits being \f[V]0\f[R]);
80 not covered (with number of hits being \f[CR]0\f[R]);
107 81 .IP \[bu] 2 .IP \[bu] 2
108 covered (with number of hits being greater than \f[V]0\f[R]).
82 covered (with number of hits being greater than \f[CR]0\f[R]).
109 83 .PP .PP
110 84 Coverage rate is defined simply as number of covered lines divided by Coverage rate is defined simply as number of covered lines divided by
111 85 number of relevant lines. number of relevant lines.
 
... ... builds, directories and files.
120 94 Data describing changes is calculated from state of files in two builds: Data describing changes is calculated from state of files in two builds:
121 95 some build and build that is considered to be its predecessor. some build and build that is considered to be its predecessor.
122 96 .SS Comparison .SS Comparison
123 .PP
124 97 Comparison accounts for hierarchy: build comparison compares all their Comparison accounts for hierarchy: build comparison compares all their
125 98 files, directory comparison compares files under specified path, file files, directory comparison compares files under specified path, file
126 99 comparison compares only one file. comparison compares only one file.
 
... ... vice versa).
140 113 Should such lines be part of diff context, they are displayed as Should such lines be part of diff context, they are displayed as
141 114 somewhat dimmed compared to lines with interesting changes. somewhat dimmed compared to lines with interesting changes.
142 115 .SS Notations .SS Notations
143 .PP
144 116 For the sake of brevity interface uses several intuitive abbreviations: For the sake of brevity interface uses several intuitive abbreviations:
145 117 .IP \[bu] 2 .IP \[bu] 2
146 118 Cov \[en] coverage; Cov \[en] coverage;
 
... ... M \[en] missed;
154 126 R \[en] relevant. R \[en] relevant.
155 127 .SH SUBCOMMANDS .SH SUBCOMMANDS
156 128 .SS Syntax of build numbers .SS Syntax of build numbers
157 .PP
158 129 Build numbers are specified in arguments for subcommands by being Build numbers are specified in arguments for subcommands by being
159 prepended with \f[V]\[at]\f[R] sign.
160 So to refer to build number \f[V]5\f[R], one would write
161 \f[V]\[at]5\f[R].
130 prepended with \f[CR]\[at]\f[R] sign.
131 So to refer to build number \f[CR]5\f[R], one would write
132 \f[CR]\[at]5\f[R].
162 133 .PP .PP
163 Build numbers start at \f[V]1\f[R], this leaves \f[V]\[at]0\f[R] unused.
134 Build numbers start at \f[CR]1\f[R], this leaves \f[CR]\[at]0\f[R]
135 unused.
164 136 It is thus repurposed to be a handy shortcut for the latest build. It is thus repurposed to be a handy shortcut for the latest build.
165 An alternative form of writing \f[V]\[at]0\f[R] is \f[V]\[at]\[at]\f[R].
137 An alternative form of writing \f[CR]\[at]0\f[R] is
138 \f[CR]\[at]\[at]\f[R].
166 139 .PP .PP
167 Build numbers can also be specified in the form of \f[V]\[at]-N\f[R], in
168 which case they select Nth to the latest build.
140 Build numbers can also be specified in the form of \f[CR]\[at]\-N\f[R],
141 in which case they select Nth to the latest build.
169 142 For example, to specify range from previous build to one build before For example, to specify range from previous build to one build before
170 that one would write \f[V]\[at]-1 \[at]-2\f[R].
143 that one would write \f[CR]\[at]\-1 \[at]\-2\f[R].
171 144 .PP .PP
172 145 Lastly, branch names can be used to specify latest build from that Lastly, branch names can be used to specify latest build from that
173 branch (e.g., \f[V]\[at]master\f[R]).
146 branch (e.g., \f[CR]\[at]master\f[R]).
174 147 .SS Resolving ambiguity .SS Resolving ambiguity
175 .PP
176 148 Some commands can take optional build number, which opens the door for Some commands can take optional build number, which opens the door for
177 149 ambiguity between file/directory names and build identifiers. ambiguity between file/directory names and build identifiers.
178 Anything that starts with \f[V]\[at]\f[R] at a suitable position on
179 command-line is assumed to be build number.
180 For files which have \f[V]\[at]\f[R] as prefix, specifying build number
150 Anything that starts with \f[CR]\[at]\f[R] at a suitable position on
151 command\-line is assumed to be build number.
152 For files which have \f[CR]\[at]\f[R] as prefix, specifying build number
181 153 becomes mandatory. becomes mandatory.
182 154 As an example: As an example:
183 155 .IP .IP
184 .nf
185 \f[C]
156 .EX
186 157 # this doesn\[aq]t work # this doesn\[aq]t work
187 uncov show \[at]strangely-named-file
158 uncov show \[at]strangely\-named\-file
188 159 # this is equivalent and works # this is equivalent and works
189 uncov show \[at]\[at] \[at]strangely-named-file
190 \f[R]
191 .fi
160 uncov show \[at]\[at] \[at]strangely\-named\-file
161 .EE
192 162 .SS Default build .SS Default build
193 .PP
194 163 If a subcommand accepts build number, in almost all cases it\[cq]s an If a subcommand accepts build number, in almost all cases it\[cq]s an
195 164 optional parameter and latest build is used when this argument is optional parameter and latest build is used when this argument is
196 165 omitted. omitted.
197 166 .SS Subcommand aliases .SS Subcommand aliases
198 .PP
199 167 Instead of requiring arguments for subcommands a different approach has Instead of requiring arguments for subcommands a different approach has
200 168 been taken. been taken.
201 169 Some commands have several names and depending on how you call them, Some commands have several names and depending on how you call them,
202 170 they act slightly differently. they act slightly differently.
203 171 .SS Paths .SS Paths
204 .PP
205 172 As a convenience when current working directory is under work tree of a As a convenience when current working directory is under work tree of a
206 repository, paths that do not start with a slash \f[V]/\f[R] are
173 repository, paths that do not start with a slash \f[CR]/\f[R] are
207 174 automatically converted to be relative to root of the repository. automatically converted to be relative to root of the repository.
208 175 .SH LIST OF SUBCOMMANDS .SH LIST OF SUBCOMMANDS
209 176 .SS build .SS build
210 .PP
211 177 Displays information about single build. Displays information about single build.
212 178 .PP .PP
213 179 \f[B]Usage: build\f[R] \f[B]Usage: build\f[R]
 
... ... Describes the last build.
218 184 .PP .PP
219 185 Describes \f[B]<build>\f[R]. Describes \f[B]<build>\f[R].
220 186 .SS builds .SS builds
221 .PP
222 187 Lists builds. Lists builds.
223 188 .PP .PP
224 189 \f[B]Usage: builds\f[R] \f[B]Usage: builds\f[R]
 
... ... Lists at most \f[B]<max list length>\f[R] most recent builds.
233 198 .PP .PP
234 199 Lists all builds. Lists all builds.
235 200 .SS changed .SS changed
236 .PP
237 201 Same as \f[B]files\f[R] subcommand, but omits listing files which have Same as \f[B]files\f[R] subcommand, but omits listing files which have
238 202 their coverage rate unchanged. their coverage rate unchanged.
239 203 .PP .PP
240 204 See description of \f[B]files\f[R] subcommand below for syntax. See description of \f[B]files\f[R] subcommand below for syntax.
241 205 .SS diff .SS diff
242 .PP
243 206 Compares builds, directories or files. Compares builds, directories or files.
244 207 Lines of files are compared by their state (i.e., changes in number of Lines of files are compared by their state (i.e., changes in number of
245 hits when both old and new values are bigger than \f[V]0\f[R] are
208 hits when both old and new values are bigger than \f[CR]0\f[R] are
246 209 treated as no change). treated as no change).
247 210 .PP .PP
248 211 \f[B]Usage: diff\f[R] \f[B]Usage: diff\f[R]
 
... ... See forms above for information about first two arguments.
263 226 If \f[B]<path>\f[R] specifies directory in either of two builds, only If \f[B]<path>\f[R] specifies directory in either of two builds, only
264 227 files under it and below are compared. files under it and below are compared.
265 228 If \f[B]<path>\f[R] specifies file, only that file is compared. If \f[B]<path>\f[R] specifies file, only that file is compared.
266 .SS diff-hits
267 .PP
229 .SS diff\-hits
268 230 Same as \f[B]diff\f[R] subcommand, but considers change of number of Same as \f[B]diff\f[R] subcommand, but considers change of number of
269 231 hits of a line to be significant change. hits of a line to be significant change.
270 232 .PP .PP
271 233 See description of \f[B]diff\f[R] subcommand above for syntax. See description of \f[B]diff\f[R] subcommand above for syntax.
272 234 .SS dirs .SS dirs
273 .PP
274 235 Lists statistics of files grouped by directories they\[cq]re located in. Lists statistics of files grouped by directories they\[cq]re located in.
275 236 .PP .PP
276 237 \f[B]Usage: dirs\f[R] \f[B]Usage: dirs\f[R]
 
... ... Lists directories of \f[B]<build>\f[R] (or last build) located under
297 258 See forms above for information about first two arguments. See forms above for information about first two arguments.
298 259 Lists directories located under \f[B]<directory path>\f[R]. Lists directories located under \f[B]<directory path>\f[R].
299 260 .SS files .SS files
300 .PP
301 261 Lists statistics about files. Lists statistics about files.
302 262 .PP .PP
303 263 \f[B]Usage: files\f[R] \f[B]Usage: files\f[R]
 
... ... See forms above for information about first two arguments.
325 285 Lists files located under \f[B]<path>\f[R] (if it\[cq]s a directory) or Lists files located under \f[B]<path>\f[R] (if it\[cq]s a directory) or
326 286 single file that exactly matches the path. single file that exactly matches the path.
327 287 .SS get .SS get
328 .PP
329 288 Dumps coverage information of a file. Dumps coverage information of a file.
330 289 .PP .PP
331 290 \f[B]Usage: get <build> <file path>\f[R] \f[B]Usage: get <build> <file path>\f[R]
332 291 .PP .PP
333 292 Prints information about the file in this form: Prints information about the file in this form:
334 293 .IP .IP
335 .nf
336 \f[C]
294 .EX
337 295 <commit> <commit>
338 296 <line1 coverage as integer> <line1 coverage as integer>
339 297 <line2 coverage as integer> <line2 coverage as integer>
340 298 <line3 coverage as integer> <line3 coverage as integer>
341 299 \&... \&...
342 \f[R]
343 .fi
300 .EE
344 301 .PP .PP
345 302 See description of \f[B]new\f[R] subcommand below for meaning of integer See description of \f[B]new\f[R] subcommand below for meaning of integer
346 303 values. values.
347 304 .SS help .SS help
348 .PP
349 305 Displays help information. Displays help information.
350 306 .PP .PP
351 307 \f[B]Usage: help\f[R] \f[B]Usage: help\f[R]
 
... ... Displays generic information about all subcommands.
356 312 .PP .PP
357 313 Displays information about a specific subcommand. Displays information about a specific subcommand.
358 314 .SS missed .SS missed
359 .PP
360 315 Same as \f[B]show\f[R] subcommand, but folds not relevant and covered Same as \f[B]show\f[R] subcommand, but folds not relevant and covered
361 316 lines and thus displays only parts of files that lack coverage. lines and thus displays only parts of files that lack coverage.
362 317 .PP .PP
363 318 See description of \f[B]show\f[R] subcommand below for syntax. See description of \f[B]show\f[R] subcommand below for syntax.
364 319 .SS new .SS new
365 .PP
366 320 Imports new build from standard input. Imports new build from standard input.
367 321 .PP .PP
368 322 \f[B]Usage: new\f[R] \f[B]Usage: new\f[R]
369 323 .PP .PP
370 324 Reads coverage information from standard input in the following format: Reads coverage information from standard input in the following format:
371 325 .IP .IP
372 .nf
373 \f[C]
326 .EX
374 327 <commit> <commit>
375 328 <ref name> <ref name>
376 329 <file name relative to repository root> <file name relative to repository root>
 
... ... Reads coverage information from standard input in the following format:
378 331 <number of lines of coverage> <number of lines of coverage>
379 332 <line1 coverage as integer> <line2 coverage as integer> ... <line1 coverage as integer> <line2 coverage as integer> ...
380 333 <all other files in the same format> <all other files in the same format>
381 \f[R]
382 .fi
334 .EE
383 335 .PP .PP
384 336 Integers have the following meaning: Integers have the following meaning:
385 337 .IP \[bu] 2 .IP \[bu] 2
386 when less than zero (specifically \f[V]-1\f[R]) \[en] line is not
338 when less than zero (specifically \f[CR]\-1\f[R]) \[en] line is not
387 339 relevant; relevant;
388 340 .IP \[bu] 2 .IP \[bu] 2
389 341 when equal to zero \[en] line is not covered (missed); when equal to zero \[en] line is not covered (missed);
390 342 .IP \[bu] 2 .IP \[bu] 2
391 343 when greater than zero \[en] line is covered and was hit that many when greater than zero \[en] line is covered and was hit that many
392 344 times. times.
393 .SS new-gcovi
394 .PP
395 Generates coverage via \f[V]gcov\f[R] and imports it.
345 .SS new\-gcovi
346 Generates coverage via \f[CR]gcov\f[R] and imports it.
396 347 .PP .PP
397 \f[B]Usage: new-gcovi [options\&...]
348 \f[B]Usage: new\-gcovi [options\&...]
398 349 [covoutroot]\f[R] [covoutroot]\f[R]
399 350 .PP .PP
400 351 \f[B]Parameters:\f[R] \f[B]Parameters:\f[R]
 
... ... Generates coverage via \f[V]gcov\f[R] and imports it.
403 354 .PP .PP
404 355 \f[B]Options:\f[R] \f[B]Options:\f[R]
405 356 .IP \[bu] 2 .IP \[bu] 2
406 \f[B]-h [ --help ]\f[R] \[en] display help message;
357 \f[B]\-h [ \-\-help ]\f[R] \[en] display help message;
407 358 .IP \[bu] 2 .IP \[bu] 2
408 \f[B]-v [ --verbose ]\f[R] \[en] print output of external commands;
359 \f[B]\-v [ \-\-verbose ]\f[R] \[en] print output of external commands;
409 360 .IP \[bu] 2 .IP \[bu] 2
410 \f[B]-e [ --exclude ] arg\f[R] \[en] specifies a path to exclude (can be
411 repeated), paths are taken to be relative to the root of the repository;
361 \f[B]\-e [ \-\-exclude ] arg\f[R] \[en] specifies a path to exclude (can
362 be repeated), paths are taken to be relative to the root of the
363 repository;
412 364 .IP \[bu] 2 .IP \[bu] 2
413 \f[B]--prefix arg\f[R] \[en] prefix to be added to relative path of
365 \f[B]\-\-prefix arg\f[R] \[en] prefix to be added to relative path of
414 366 sources; sources;
415 367 .IP \[bu] 2 .IP \[bu] 2
416 \f[B]--ref-name arg\f[R] \[en] forces custom ref name;
368 \f[B]\-\-ref\-name arg\f[R] \[en] forces custom ref name;
417 369 .IP \[bu] 2 .IP \[bu] 2
418 \f[B]-c [ --capture-worktree ]\f[R] \[en] make a dangling commit if
370 \f[B]\-c [ \-\-capture\-worktree ]\f[R] \[en] make a dangling commit if
419 371 working directory is dirty. working directory is dirty.
420 372 .PP .PP
421 To do its work this subcommand invokes \f[V]gcov\f[R] and then parses
373 To do its work this subcommand invokes \f[CR]gcov\f[R] and then parses
422 374 its output in intermediate format, which is only mostly stable so usage its output in intermediate format, which is only mostly stable so usage
423 with some versions of \f[V]gcov\f[R] might require changes.
424 .SS new-json
425 .PP
375 with some versions of \f[CR]gcov\f[R] might require changes.
376 .SS new\-json
426 377 Imports new build in JSON format from standard input. Imports new build in JSON format from standard input.
427 378 .PP .PP
428 \f[B]Usage: new-json\f[R]
379 \f[B]Usage: new\-json\f[R]
429 380 .PP .PP
430 381 Reads coverage information from standard input in the following format: Reads coverage information from standard input in the following format:
431 382 .IP .IP
432 .nf
433 \f[C]
383 .EX
434 384 <prefix that doesn\[aq]t contain { character> <prefix that doesn\[aq]t contain { character>
435 385 { {
436 386 \[dq]source_files\[dq]: [ \[dq]source_files\[dq]: [
 
... ... Reads coverage information from standard input in the following format:
449 399 \[dq]branch\[dq]: \[dq]<branch>\[dq] \[dq]branch\[dq]: \[dq]<branch>\[dq]
450 400 } }
451 401 } }
452 \f[R]
453 .fi
402 .EE
454 403 .PP .PP
455 404 Any other elements are ignored. Any other elements are ignored.
456 405 .SS regress .SS regress
457 .PP
458 406 Same as \f[B]diff\f[R] subcommand, but displays introduced lines that Same as \f[B]diff\f[R] subcommand, but displays introduced lines that
459 407 aren\[cq]t covered. aren\[cq]t covered.
460 408 .PP .PP
461 409 See description of \f[B]diff\f[R] subcommand above for syntax. See description of \f[B]diff\f[R] subcommand above for syntax.
462 410 .SS show .SS show
463 .PP
464 411 Prints whole build, files under directory or a single file with coverage Prints whole build, files under directory or a single file with coverage
465 412 information. information.
466 413 .PP .PP
 
... ... Prints files of \f[B]<build>\f[R] (or last build) located under
478 425 \f[B]<path>\f[R] if it specifies directory or one specific file. \f[B]<path>\f[R] if it specifies directory or one specific file.
479 426 .SH CONFIGURATION .SH CONFIGURATION
480 427 .SS Location and format .SS Location and format
481 .PP
482 Configuration is read from \f[B]<repository-directory>/uncov.ini\f[R]
428 Configuration is read from \f[B]<repository\-directory>/uncov.ini\f[R]
483 429 file. file.
484 430 If it doesn\[cq]t exist or contains invalid data (e.g., duplicated If it doesn\[cq]t exist or contains invalid data (e.g., duplicated
485 431 keys), default settings remain intact. keys), default settings remain intact.
486 432 .PP .PP
487 The file has regular ini-format and can contain either comments that
488 start with \f[B];\f[R] or key-value pairs like \f[B]tab-size = 2\f[R]
433 The file has regular ini\-format and can contain either comments that
434 start with \f[B];\f[R] or key\-value pairs like \f[B]tab\-size = 2\f[R]
489 435 (with or without spaces). (with or without spaces).
490 436 .PP .PP
491 437 Values are interpreted according to types of their keys. Values are interpreted according to types of their keys.
492 438 Keys with values that are not convertible to corresponding types are Keys with values that are not convertible to corresponding types are
493 439 ignored. ignored.
494 440 .SS Available settings .SS Available settings
495 .PP
496 441 Format of each entry below: Format of each entry below:
497 442 .IP .IP
498 .nf
499 \f[C]
443 .EX
500 444 <option> (<type>, [app:] <default value>) <option> (<type>, [app:] <default value>)
501 445
502 446 <description> <description>
503 \f[R]
504 .fi
447 .EE
505 448 .PP .PP
506 \f[B]low-bound\f[R] (floating point, 70)
449 \f[B]low\-bound\f[R] (floating point, 70)
507 450 .PP .PP
508 451 Percentage boundary between low and medium coverage levels. Percentage boundary between low and medium coverage levels.
509 452 Normalized to be in the [0, 100] range. Normalized to be in the [0, 100] range.
510 If \f[B]low-bound > hi-bound\f[R], their values are swapped.
453 If \f[B]low\-bound > hi\-bound\f[R], their values are swapped.
511 454 .PP .PP
512 \f[B]hi-bound\f[R] (floating point, 90)
455 \f[B]hi\-bound\f[R] (floating point, 90)
513 456 .PP .PP
514 457 Percentage boundary between medium and high coverage levels. Percentage boundary between medium and high coverage levels.
515 458 Normalized to be in the [0, 100] range. Normalized to be in the [0, 100] range.
516 If \f[B]low-bound > hi-bound\f[R], their values are swapped.
459 If \f[B]low\-bound > hi\-bound\f[R], their values are swapped.
517 460 .PP .PP
518 \f[B]tab-size\f[R] (integer, 4)
461 \f[B]tab\-size\f[R] (integer, 4)
519 462 .PP .PP
520 463 Width of tabulation in spaces. Width of tabulation in spaces.
521 464 .PP .PP
522 \f[B]min-fold-size\f[R] (integer, \f[B]uncov\f[R]: 3,
523 \f[B]uncov-web\f[R]: 4)
465 \f[B]min\-fold\-size\f[R] (integer, \f[B]uncov\f[R]: 3,
466 \f[B]uncov\-web\f[R]: 4)
524 467 .PP .PP
525 468 Minimal number of lines to be folded. Minimal number of lines to be folded.
526 469 .PP .PP
527 \f[B]fold-context\f[R] (integer, 1)
470 \f[B]fold\-context\f[R] (integer, 1)
528 471 .PP .PP
529 472 Number of visible lines above and below changes. Number of visible lines above and below changes.
530 473 .PP .PP
531 \f[B]diff-show-lineno\f[R] (boolean, \f[B]uncov\f[R]: false,
532 \f[B]uncov-web\f[R]: true)
474 \f[B]diff\-show\-lineno\f[R] (boolean, \f[B]uncov\f[R]: false,
475 \f[B]uncov\-web\f[R]: true)
533 476 .PP .PP
534 477 Whether line numbers are displayed in diffs. Whether line numbers are displayed in diffs.
535 478 .SH FILES .SH FILES
479 \f[B]<data\-directory>\f[R] in the following is either git\-directory
480 for a worktree (see \f[B]git\-worktree\f[R](1)) or for the repository
481 that owns it, whichever has either of those files when checking
482 directories in the order they are mentioned.
483 If no files found, repository\[cq]s git\-directory is used.
536 484 .PP .PP
537 \f[B]<data-directory>\f[R] in the following is either git-directory for
538 a worktree (see \f[B]git-worktree\f[R](1)) or for the repository that
539 owns it, whichever has either of those files when checking directories
540 in the order they are mentioned.
541 If no files found, repository\[cq]s git-directory is used.
485 \f[B]<data\-directory>/uncov.sqlite\f[R] \[en] storage of coverage data.
542 486 .PP .PP
543 \f[B]<data-directory>/uncov.sqlite\f[R] \[en] storage of coverage data.
544 .PP
545 \f[B]<data-directory>/uncov.ini\f[R] \[en] configuration.
487 \f[B]<data\-directory>/uncov.ini\f[R] \[en] configuration.
546 488 .SH SEE ALSO .SH SEE ALSO
547 .PP
548 \f[B]uncov-gcov\f[R](1), \f[B]uncov-web\f[R](1)
489 \f[B]uncov\-gcov\f[R](1), \f[B]uncov\-web\f[R](1)
549 490 .SH AUTHORS .SH AUTHORS
550 491 xaizek <xaizek@posteo.net>. 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