File docs/uncov-gcov.1 changed (mode: 100644) (index 46aa33d..f5815db) |
1 |
|
.\" Automatically generated by Pandoc 2.13 |
|
|
1 |
|
.\" Automatically generated by Pandoc 2.17.1.1 |
2 |
2 |
.\" |
.\" |
3 |
|
.TH "uncov-gcov" "1" "November 14, 2021" "uncov v0.4" "" |
|
|
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.4" "" |
4 |
18 |
.hy |
.hy |
5 |
19 |
.SH NAME |
.SH NAME |
6 |
20 |
.PP |
.PP |
|
... |
... |
It might be a good idea to switch to using \[lq]uncov new-gcovi\[rq] |
16 |
30 |
subcommand. |
subcommand. |
17 |
31 |
.SH SYNOPSIS |
.SH SYNOPSIS |
18 |
32 |
.PP |
.PP |
19 |
|
\f[B]uncov-gcov\f[R] \f[B]-h|\[en]help\f[R] |
|
|
33 |
|
\f[B]uncov-gcov\f[R] \f[B]-h|--help\f[R] |
20 |
34 |
.PP |
.PP |
21 |
|
\f[B]uncov-gcov\f[R] \f[B]-v|\[en]version\f[R] |
|
|
35 |
|
\f[B]uncov-gcov\f[R] \f[B]-v|--version\f[R] |
22 |
36 |
.PP |
.PP |
23 |
37 |
\f[B]uncov-gcov\f[R] \f[B][<options>\&...]\f[R] |
\f[B]uncov-gcov\f[R] \f[B][<options>\&...]\f[R] |
24 |
38 |
.SH OPTIONS |
.SH OPTIONS |
25 |
|
.SS \f[B]\[en]help, -h\f[R] |
|
|
39 |
|
.SS \f[B]--help, -h\f[R] |
26 |
40 |
.PP |
.PP |
27 |
41 |
Displays short usage help. |
Displays short usage help. |
28 |
|
.SS \f[B]\[en]version, -v\f[R] |
|
|
42 |
|
.SS \f[B]--version, -v\f[R] |
29 |
43 |
.PP |
.PP |
30 |
44 |
Displays version information. |
Displays version information. |
31 |
|
.SS \f[B]\[en]verbose\f[R] |
|
|
45 |
|
.SS \f[B]--verbose\f[R] |
32 |
46 |
.PP |
.PP |
33 |
47 |
Print verbose messages. |
Print verbose messages. |
34 |
|
.SS \f[B]\[en]dryrun\f[R] |
|
|
48 |
|
.SS \f[B]--dryrun\f[R] |
35 |
49 |
.PP |
.PP |
36 |
50 |
Run the script without printing report. |
Run the script without printing report. |
37 |
|
.SS \f[B]\[en]gcov\f[R] [=gcov] |
|
|
51 |
|
.SS \f[B]--gcov\f[R] [=gcov] |
38 |
52 |
.PP |
.PP |
39 |
53 |
Set the location of gcov. |
Set the location of gcov. |
40 |
|
.SS \f[B]\[en]gcov-options\f[R] [=\[dq]\[dq]] |
|
|
54 |
|
.SS \f[B]--gcov-options\f[R] [=\[lq]\[rq]] |
41 |
55 |
.PP |
.PP |
42 |
56 |
Set the options given to gcov. |
Set the options given to gcov. |
43 |
|
.SS \f[B]-r\f[R], \f[B]\[en]root\f[R] [=.] |
|
|
57 |
|
.SS \f[B]-r\f[R], \f[B]--root\f[R] [=.] |
44 |
58 |
.PP |
.PP |
45 |
59 |
Set the root directory. |
Set the root directory. |
46 |
|
.SS \f[B]-b\f[R], \f[B]\[en]build-root\f[R] [={discovered}] |
|
|
60 |
|
.SS \f[B]-b\f[R], \f[B]--build-root\f[R] [={discovered}] |
47 |
61 |
.PP |
.PP |
48 |
62 |
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 |
49 |
63 |
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 |
|
... |
... |
often relative to the directory from which the compiler was run and |
51 |
65 |
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 |
52 |
66 |
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 |
53 |
67 |
source files. |
source files. |
54 |
|
.SS \f[B]\[en]collect-root\f[R] [={value of \[en]root}] |
|
|
68 |
|
.SS \f[B]--collect-root\f[R] [={value of --root}] |
55 |
69 |
.PP |
.PP |
56 |
70 |
Directory to look gcov files in. |
Directory to look gcov files in. |
57 |
|
.SS \f[B]-e\f[R], \f[B]\[en]exclude\f[R] [=\[dq]\[dq]] |
|
|
71 |
|
.SS \f[B]-e\f[R], \f[B]--exclude\f[R] [=\[lq]\[rq]] |
58 |
72 |
.PP |
.PP |
59 |
73 |
List of paths to exclude. |
List of paths to exclude. |
60 |
74 |
Can be specifieid multiple times. |
Can be specifieid multiple times. |
|
... |
... |
Examples: |
63 |
77 |
.IP |
.IP |
64 |
78 |
.nf |
.nf |
65 |
79 |
\f[C] |
\f[C] |
66 |
|
uncov-gcov --exclude build-release --exclude build-debug ... |
|
67 |
|
uncov-gcov --exclude build-release build-debug ... |
|
68 |
|
uncov-gcov --exclude build* ... |
|
|
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* ... |
69 |
83 |
\f[R] |
\f[R] |
70 |
84 |
.fi |
.fi |
71 |
|
.SS \f[B]-i\f[R], \f[B]\[en]include\f[R] [=\[dq]\[dq]] |
|
|
85 |
|
.SS \f[B]-i\f[R], \f[B]--include\f[R] [=\[lq]\[rq]] |
72 |
86 |
.PP |
.PP |
73 |
87 |
List of paths to include. |
List of paths to include. |
74 |
88 |
Can be specifieid multiple times. |
Can be specifieid multiple times. |
75 |
|
See \f[B]\[en]exclude\f[R] for examples. |
|
76 |
|
.SS \f[B]-E\f[R], \f[B]\[en]exclude-pattern\f[R] [=\[dq]\[dq]] |
|
|
89 |
|
See \f[B]--exclude\f[R] for examples. |
|
90 |
|
.SS \f[B]-E\f[R], \f[B]--exclude-pattern\f[R] [=\[lq]\[rq]] |
77 |
91 |
.PP |
.PP |
78 |
92 |
Set exclude file/directory pattern. |
Set exclude file/directory pattern. |
79 |
|
.SS \f[B]-x\f[R], \f[B]\[en]extension\f[R] [=.h,.hh,.hpp,.hxx,.c,.cc,.cpp,.cxx,.m,.mm] |
|
|
93 |
|
.SS \f[B]-x\f[R], \f[B]--extension\f[R] [=.h,.hh,.hpp,.hxx,.c,.cc,.cpp,.cxx,.m,.mm] |
80 |
94 |
.PP |
.PP |
81 |
95 |
Set extension of files to process. |
Set extension of files to process. |
82 |
|
.SS \f[B]-n\f[R], \f[B]\[en]no-gcov\f[R] |
|
|
96 |
|
.SS \f[B]-n\f[R], \f[B]--no-gcov\f[R] |
83 |
97 |
.PP |
.PP |
84 |
98 |
Do not run gcov. |
Do not run gcov. |
85 |
|
.SS \f[B]\[en]encodings\f[R] [=utf-8,latin-1] |
|
|
99 |
|
.SS \f[B]--encodings\f[R] [=utf-8,latin-1] |
86 |
100 |
.PP |
.PP |
87 |
101 |
Source encodings to try in order of preference. |
Source encodings to try in order of preference. |
88 |
|
.SS \f[B]\[en]dump\f[R] <file> |
|
|
102 |
|
.SS \f[B]--dump\f[R] <file> |
89 |
103 |
.PP |
.PP |
90 |
104 |
Dump JSON payload to a file. |
Dump JSON payload to a file. |
91 |
|
.SS \f[B]\[en]follow-symlinks\f[R] |
|
|
105 |
|
.SS \f[B]--follow-symlinks\f[R] |
92 |
106 |
.PP |
.PP |
93 |
107 |
Follow symlinks. |
Follow symlinks. |
94 |
|
.SS \f[B]-c\f[R], \f[B]\[en]capture-worktree\f[R] |
|
|
108 |
|
.SS \f[B]-c\f[R], \f[B]--capture-worktree\f[R] |
95 |
109 |
.PP |
.PP |
96 |
110 |
Make a dangling commit if working directory is dirty. |
Make a dangling commit if working directory is dirty. |
97 |
|
.SS \f[B]\[en]ref-name\f[R] [={discovered}] |
|
|
111 |
|
.SS \f[B]--ref-name\f[R] [={discovered}] |
98 |
112 |
.PP |
.PP |
99 |
113 |
Force custom ref name. |
Force custom ref name. |
100 |
|
.SS \f[B]\[en]cpp-dtor-invocations\f[R] |
|
|
114 |
|
.SS \f[B]--cpp-dtor-invocations\f[R] |
101 |
115 |
.PP |
.PP |
102 |
116 |
Count coverage for C++ destructor invocations, which tends to show up at |
Count coverage for C++ destructor invocations, which tends to show up at |
103 |
|
lines that have the closing brace (\f[C]{\f[R]). |
|
|
117 |
|
lines that have the closing brace (\f[V]{\f[R]). |
104 |
118 |
.SH USAGE |
.SH USAGE |
105 |
119 |
.PP |
.PP |
106 |
120 |
uncov-gcov can be used to generate coverage, but it seems to not play |
uncov-gcov can be used to generate coverage, but it seems to not play |
|
... |
... |
find . -name \[aq]*.gcda\[aq] -delete |
118 |
132 |
# 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) |
119 |
133 |
find . -name \[aq]*.o\[aq] -exec gcov -p {} + |
find . -name \[aq]*.o\[aq] -exec gcov -p {} + |
120 |
134 |
|
|
121 |
|
# generage and combine coverage reports (--capture-worktree automatically |
|
|
135 |
|
# generage and combine coverage reports (-\[rs]-capture-worktree automatically |
122 |
136 |
# makes stray commit if repository is dirty) |
# makes stray commit if repository is dirty) |
123 |
|
uncov-gcov --root . --no-gcov --capture-worktree --exclude tests | uncov new |
|
|
137 |
|
uncov-gcov -\[rs]-root . -\[rs]-no-gcov -\[rs]-capture-worktree -\[rs]-exclude tests | uncov new |
124 |
138 |
|
|
125 |
139 |
# remove coverage reports |
# remove coverage reports |
126 |
140 |
find . -name \[aq]*.gcov\[aq] -delete |
find . -name \[aq]*.gcov\[aq] -delete |
File docs/uncov-gcov/03-options.md changed (mode: 100644) (index a099b2e..ce31b57) |
1 |
1 |
OPTIONS |
OPTIONS |
2 |
2 |
======= |
======= |
3 |
3 |
|
|
4 |
|
**--help, -h** |
|
5 |
|
-------------- |
|
|
4 |
|
**-\-help, -h** |
|
5 |
|
--------------- |
6 |
6 |
|
|
7 |
7 |
Displays short usage help. |
Displays short usage help. |
8 |
8 |
|
|
9 |
|
**--version, -v** |
|
10 |
|
----------------- |
|
|
9 |
|
**-\-version, -v** |
|
10 |
|
------------------ |
11 |
11 |
|
|
12 |
12 |
Displays version information. |
Displays version information. |
13 |
13 |
|
|
14 |
|
**--verbose** |
|
15 |
|
------------- |
|
|
14 |
|
**-\-verbose** |
|
15 |
|
-------------- |
16 |
16 |
|
|
17 |
17 |
Print verbose messages. |
Print verbose messages. |
18 |
18 |
|
|
19 |
|
**--dryrun** |
|
20 |
|
------------ |
|
|
19 |
|
**-\-dryrun** |
|
20 |
|
------------- |
21 |
21 |
|
|
22 |
22 |
Run the script without printing report. |
Run the script without printing report. |
23 |
23 |
|
|
24 |
|
**--gcov** [=gcov] |
|
25 |
|
------------------ |
|
|
24 |
|
**-\-gcov** [=gcov] |
|
25 |
|
------------------- |
26 |
26 |
|
|
27 |
27 |
Set the location of gcov. |
Set the location of gcov. |
28 |
28 |
|
|
29 |
|
**--gcov-options** [=""] |
|
30 |
|
------------------------ |
|
|
29 |
|
**-\-gcov-options** [=""] |
|
30 |
|
------------------------- |
31 |
31 |
|
|
32 |
32 |
Set the options given to gcov. |
Set the options given to gcov. |
33 |
33 |
|
|
34 |
|
**-r**, **--root** [=.] |
|
35 |
|
----------------------- |
|
|
34 |
|
**-r**, **-\-root** [=.] |
|
35 |
|
------------------------ |
36 |
36 |
|
|
37 |
37 |
Set the root directory. |
Set the root directory. |
38 |
38 |
|
|
39 |
|
**-b**, **--build-root** [={discovered}] |
|
40 |
|
---------------------------------------- |
|
|
39 |
|
**-b**, **-\-build-root** [={discovered}] |
|
40 |
|
----------------------------------------- |
41 |
41 |
|
|
42 |
42 |
Set the directory from which gcov will be called; by default gcov is run in the |
Set the directory from which gcov will be called; by default gcov is run in the |
43 |
43 |
directory of the .o files; however the paths of the sources are often relative |
directory of the .o files; however the paths of the sources are often relative |
|
... |
... |
to the directory from which the compiler was run and these relative paths are |
45 |
45 |
saved in the .o file; when this happens, gcov needs to run in the same directory |
saved in the .o file; when this happens, gcov needs to run in the same directory |
46 |
46 |
as the compiler in order to find the source files. |
as the compiler in order to find the source files. |
47 |
47 |
|
|
48 |
|
**--collect-root** [={value of --root}] |
|
49 |
|
--------------------------------------- |
|
|
48 |
|
**-\-collect-root** [={value of -\-root}] |
|
49 |
|
---------------------------------------- |
50 |
50 |
|
|
51 |
51 |
Directory to look gcov files in. |
Directory to look gcov files in. |
52 |
52 |
|
|
53 |
|
**-e**, **--exclude** [=""] |
|
54 |
|
--------------------------- |
|
|
53 |
|
**-e**, **-\-exclude** [=""] |
|
54 |
|
---------------------------- |
55 |
55 |
|
|
56 |
56 |
List of paths to exclude. Can be specifieid multiple times. |
List of paths to exclude. Can be specifieid multiple times. |
57 |
57 |
|
|
58 |
58 |
Examples: |
Examples: |
59 |
59 |
|
|
60 |
|
uncov-gcov --exclude build-release --exclude build-debug ... |
|
61 |
|
uncov-gcov --exclude build-release build-debug ... |
|
62 |
|
uncov-gcov --exclude build* ... |
|
|
60 |
|
uncov-gcov -\-exclude build-release -\-exclude build-debug ... |
|
61 |
|
uncov-gcov -\-exclude build-release build-debug ... |
|
62 |
|
uncov-gcov -\-exclude build* ... |
63 |
63 |
|
|
64 |
|
**-i**, **--include** [=""] |
|
65 |
|
--------------------------- |
|
|
64 |
|
**-i**, **-\-include** [=""] |
|
65 |
|
---------------------------- |
66 |
66 |
|
|
67 |
|
List of paths to include. Can be specifieid multiple times. See **--exclude** |
|
|
67 |
|
List of paths to include. Can be specifieid multiple times. See **-\-exclude** |
68 |
68 |
for examples. |
for examples. |
69 |
69 |
|
|
70 |
|
**-E**, **--exclude-pattern** [=""] |
|
71 |
|
----------------------------------- |
|
|
70 |
|
**-E**, **-\-exclude-pattern** [=""] |
|
71 |
|
------------------------------------ |
72 |
72 |
|
|
73 |
73 |
Set exclude file/directory pattern. |
Set exclude file/directory pattern. |
74 |
74 |
|
|
75 |
|
**-x**, **--extension** [=.h,.hh,.hpp,.hxx,.c,.cc,.cpp,.cxx,.m,.mm] |
|
76 |
|
------------------------------------------------------------------- |
|
|
75 |
|
**-x**, **-\-extension** [=.h,.hh,.hpp,.hxx,.c,.cc,.cpp,.cxx,.m,.mm] |
|
76 |
|
-------------------------------------------------------------------- |
77 |
77 |
|
|
78 |
78 |
Set extension of files to process. |
Set extension of files to process. |
79 |
79 |
|
|
80 |
|
**-n**, **--no-gcov** |
|
81 |
|
--------------------- |
|
|
80 |
|
**-n**, **-\-no-gcov** |
|
81 |
|
---------------------- |
82 |
82 |
|
|
83 |
83 |
Do not run gcov. |
Do not run gcov. |
84 |
84 |
|
|
85 |
|
**--encodings** [=utf-8,latin-1] |
|
86 |
|
-------------------------------- |
|
|
85 |
|
**-\-encodings** [=utf-8,latin-1] |
|
86 |
|
--------------------------------- |
87 |
87 |
|
|
88 |
88 |
Source encodings to try in order of preference. |
Source encodings to try in order of preference. |
89 |
89 |
|
|
90 |
|
**--dump** \<file\> |
|
91 |
|
------------------- |
|
|
90 |
|
**-\-dump** \<file\> |
|
91 |
|
-------------------- |
92 |
92 |
|
|
93 |
93 |
Dump JSON payload to a file. |
Dump JSON payload to a file. |
94 |
94 |
|
|
95 |
|
**--follow-symlinks** |
|
96 |
|
--------------------- |
|
|
95 |
|
**-\-follow-symlinks** |
|
96 |
|
---------------------- |
97 |
97 |
|
|
98 |
98 |
Follow symlinks. |
Follow symlinks. |
99 |
99 |
|
|
100 |
|
**-c**, **--capture-worktree** |
|
101 |
|
------------------------------ |
|
|
100 |
|
**-c**, **-\-capture-worktree** |
|
101 |
|
------------------------------- |
102 |
102 |
|
|
103 |
103 |
Make a dangling commit if working directory is dirty. |
Make a dangling commit if working directory is dirty. |
104 |
104 |
|
|
105 |
|
**--ref-name** [={discovered}] |
|
106 |
|
------------------------------ |
|
|
105 |
|
**-\-ref-name** [={discovered}] |
|
106 |
|
------------------------------- |
107 |
107 |
|
|
108 |
108 |
Force custom ref name. |
Force custom ref name. |
109 |
109 |
|
|
110 |
|
**--cpp-dtor-invocations** |
|
111 |
|
-------------------------- |
|
|
110 |
|
**-\-cpp-dtor-invocations** |
|
111 |
|
--------------------------- |
112 |
112 |
|
|
113 |
113 |
Count coverage for C++ destructor invocations, which tends to show up at lines |
Count coverage for C++ destructor invocations, which tends to show up at lines |
114 |
114 |
that have the closing brace (`{`). |
that have the closing brace (`{`). |
File docs/uncov.1 changed (mode: 100644) (index 2be20f6..7581f6d) |
1 |
|
.\" Automatically generated by Pandoc 2.13 |
|
|
1 |
|
.\" Automatically generated by Pandoc 2.17.1.1 |
2 |
2 |
.\" |
.\" |
3 |
|
.TH "uncov" "1" "November 14, 2021" "uncov v0.4" "" |
|
|
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.4" "" |
4 |
18 |
.hy |
.hy |
5 |
19 |
.SH NAME |
.SH NAME |
6 |
20 |
.PP |
.PP |
|
... |
... |
Displays short usage help. |
23 |
37 |
Displays version information. |
Displays version information. |
24 |
38 |
.SH DESCRIPTION |
.SH DESCRIPTION |
25 |
39 |
.PP |
.PP |
26 |
|
\f[C]uncov\f[R] operates a number of entities, which are directly linked |
|
|
40 |
|
\f[V]uncov\f[R] operates a number of entities, which are directly linked |
27 |
41 |
to subcommands and information they output. |
to subcommands and information they output. |
28 |
42 |
Below you can find their description. |
Below you can find their description. |
29 |
43 |
.SS Repository |
.SS Repository |
30 |
44 |
.PP |
.PP |
31 |
45 |
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 |
32 |
|
(not worktree one) is used to store data of \f[C]uncov\f[R] itself. |
|
|
46 |
|
(not worktree one) is used to store data of \f[V]uncov\f[R] itself. |
33 |
47 |
While the relation by default is of one-to-one kind, same |
While the relation by default is of one-to-one kind, same |
34 |
|
\f[C]uncov\f[R] data can be shared by multiple copies of the same |
|
35 |
|
repository by linking or copying \f[C]uncov.sqlite\f[R] file manually. |
|
|
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. |
36 |
50 |
.PP |
.PP |
37 |
51 |
Repository that corresponds to current working directory is discovered |
Repository that corresponds to current working directory is discovered |
38 |
52 |
automatically and doesn\[cq]t need to be specified explicitly. |
automatically and doesn\[cq]t need to be specified explicitly. |
39 |
53 |
Otherwise \f[B]<repo-path>\f[R] can point either to repository directory |
Otherwise \f[B]<repo-path>\f[R] can point either to repository directory |
40 |
|
(\f[C].git\f[R]) or its main worktree (doesn\[cq]t seem to work with |
|
|
54 |
|
(\f[V].git\f[R]) or its main worktree (doesn\[cq]t seem to work with |
41 |
55 |
secondary worktrees). |
secondary worktrees). |
42 |
56 |
.SS Builds |
.SS Builds |
43 |
57 |
.PP |
.PP |
44 |
|
The largest entity \f[C]uncov\f[R] operates within repository is a |
|
|
58 |
|
The largest entity \f[V]uncov\f[R] operates within repository is a |
45 |
59 |
build. |
build. |
46 |
60 |
A build has the following properties: |
A build has the following properties: |
47 |
61 |
.IP \[bu] 2 |
.IP \[bu] 2 |
48 |
|
number identifying the build (greater than \f[C]0\f[R]); |
|
|
62 |
|
number identifying the build (greater than \f[V]0\f[R]); |
49 |
63 |
.IP \[bu] 2 |
.IP \[bu] 2 |
50 |
64 |
name of reference within repository (branch usually); |
name of reference within repository (branch usually); |
51 |
65 |
.IP \[bu] 2 |
.IP \[bu] 2 |
|
... |
... |
path within repository; |
64 |
78 |
coverage information (basically an array specifying which lines are |
coverage information (basically an array specifying which lines are |
65 |
79 |
covered); |
covered); |
66 |
80 |
.IP \[bu] 2 |
.IP \[bu] 2 |
67 |
|
MD5 hash (to verify that \f[C]uncov\f[R] state is consistent with |
|
|
81 |
|
MD5 hash (to verify that \f[V]uncov\f[R] state is consistent with |
68 |
82 |
repository). |
repository). |
69 |
83 |
.SS Directories |
.SS Directories |
70 |
84 |
.PP |
.PP |
|
... |
... |
Directory is just a sum of information of all files it contains. |
76 |
90 |
.PP |
.PP |
77 |
91 |
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 |
78 |
92 |
builds is imposed, which currently simply assumes that for build number |
builds is imposed, which currently simply assumes that for build number |
79 |
|
\f[C]N\f[R] there is a \f[I]previous build\f[R] with number |
|
80 |
|
\f[C]N - 1\f[R] (when \f[C]N > 0\f[R], build number \f[C]0\f[R] has no |
|
|
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 |
81 |
95 |
previous build). |
previous build). |
82 |
96 |
.SS Statistics |
.SS Statistics |
83 |
97 |
.PP |
.PP |
|
... |
... |
So each source line must be in one of three states: |
89 |
103 |
.IP \[bu] 2 |
.IP \[bu] 2 |
90 |
104 |
not relevant; |
not relevant; |
91 |
105 |
.IP \[bu] 2 |
.IP \[bu] 2 |
92 |
|
not covered (with number of hits being \f[C]0\f[R]); |
|
|
106 |
|
not covered (with number of hits being \f[V]0\f[R]); |
93 |
107 |
.IP \[bu] 2 |
.IP \[bu] 2 |
94 |
|
covered (with number of hits being greater than \f[C]0\f[R]). |
|
|
108 |
|
covered (with number of hits being greater than \f[V]0\f[R]). |
95 |
109 |
.PP |
.PP |
96 |
110 |
Coverage rate is defined simply as number of covered lines divided by |
Coverage rate is defined simply as number of covered lines divided by |
97 |
111 |
number of relevant lines. |
number of relevant lines. |
|
... |
... |
R \[en] relevant. |
142 |
156 |
.SS Syntax of build numbers |
.SS Syntax of build numbers |
143 |
157 |
.PP |
.PP |
144 |
158 |
Build numbers are specified in arguments for subcommands by being |
Build numbers are specified in arguments for subcommands by being |
145 |
|
prepended with \f[C]\[at]\f[R] sign. |
|
146 |
|
So to refer to build number \f[C]5\f[R], one would write |
|
147 |
|
\f[C]\[at]5\f[R]. |
|
|
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]. |
148 |
162 |
.PP |
.PP |
149 |
|
Build numbers start at \f[C]1\f[R], this leaves \f[C]\[at]0\f[R] unused. |
|
|
163 |
|
Build numbers start at \f[V]1\f[R], this leaves \f[V]\[at]0\f[R] unused. |
150 |
164 |
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. |
151 |
|
An alternative form of writing \f[C]\[at]0\f[R] is \f[C]\[at]\[at]\f[R]. |
|
|
165 |
|
An alternative form of writing \f[V]\[at]0\f[R] is \f[V]\[at]\[at]\f[R]. |
152 |
166 |
.PP |
.PP |
153 |
|
Build numbers can also be specified in the form of \f[C]\[at]-N\f[R], in |
|
|
167 |
|
Build numbers can also be specified in the form of \f[V]\[at]-N\f[R], in |
154 |
168 |
which case they select Nth to the latest build. |
which case they select Nth to the latest build. |
155 |
169 |
For example, to specify range from previous build to one build before |
For example, to specify range from previous build to one build before |
156 |
|
that one would write \f[C]\[at]-1 \[at]-2\f[R]. |
|
|
170 |
|
that one would write \f[V]\[at]-1 \[at]-2\f[R]. |
157 |
171 |
.PP |
.PP |
158 |
172 |
Lastly, branch names can be used to specify latest build from that |
Lastly, branch names can be used to specify latest build from that |
159 |
|
branch (e.g., \f[C]\[at]master\f[R]). |
|
|
173 |
|
branch (e.g., \f[V]\[at]master\f[R]). |
160 |
174 |
.SS Resolving ambiguity |
.SS Resolving ambiguity |
161 |
175 |
.PP |
.PP |
162 |
176 |
Some commands can take optional build number, which opens the door for |
Some commands can take optional build number, which opens the door for |
163 |
177 |
ambiguity between file/directory names and build identifiers. |
ambiguity between file/directory names and build identifiers. |
164 |
|
Anything that starts with \f[C]\[at]\f[R] at a suitable position on |
|
|
178 |
|
Anything that starts with \f[V]\[at]\f[R] at a suitable position on |
165 |
179 |
command-line is assumed to be build number. |
command-line is assumed to be build number. |
166 |
|
For files which have \f[C]\[at]\f[R] as prefix, specifying build number |
|
|
180 |
|
For files which have \f[V]\[at]\f[R] as prefix, specifying build number |
167 |
181 |
becomes mandatory. |
becomes mandatory. |
168 |
182 |
As an example: |
As an example: |
169 |
183 |
.IP |
.IP |
|
... |
... |
they act slightly differently. |
189 |
203 |
.SS Paths |
.SS Paths |
190 |
204 |
.PP |
.PP |
191 |
205 |
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 |
192 |
|
repository, paths that do not start with a slash \f[C]/\f[R] are |
|
|
206 |
|
repository, paths that do not start with a slash \f[V]/\f[R] are |
193 |
207 |
automatically converted to be relative to root of the repository. |
automatically converted to be relative to root of the repository. |
194 |
208 |
.SH LIST OF SUBCOMMANDS |
.SH LIST OF SUBCOMMANDS |
195 |
209 |
.SS build |
.SS build |
|
... |
... |
See description of \f[B]files\f[R] subcommand below for syntax. |
228 |
242 |
.PP |
.PP |
229 |
243 |
Compares builds, directories or files. |
Compares builds, directories or files. |
230 |
244 |
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 |
231 |
|
hits when both old and new values are bigger than \f[C]0\f[R] are |
|
|
245 |
|
hits when both old and new values are bigger than \f[V]0\f[R] are |
232 |
246 |
treated as no change). |
treated as no change). |
233 |
247 |
.PP |
.PP |
234 |
248 |
\f[B]Usage: diff\f[R] |
\f[B]Usage: diff\f[R] |
|
... |
... |
Reads coverage information from standard input in the following format: |
369 |
383 |
.PP |
.PP |
370 |
384 |
Integers have the following meaning: |
Integers have the following meaning: |
371 |
385 |
.IP \[bu] 2 |
.IP \[bu] 2 |
372 |
|
when less than zero (specifically \f[C]-1\f[R]) \[en] line is not |
|
|
386 |
|
when less than zero (specifically \f[V]-1\f[R]) \[en] line is not |
373 |
387 |
relevant; |
relevant; |
374 |
388 |
.IP \[bu] 2 |
.IP \[bu] 2 |
375 |
389 |
when equal to zero \[en] line is not covered (missed); |
when equal to zero \[en] line is not covered (missed); |
|
... |
... |
when greater than zero \[en] line is covered and was hit that many |
378 |
392 |
times. |
times. |
379 |
393 |
.SS new-gcovi |
.SS new-gcovi |
380 |
394 |
.PP |
.PP |
381 |
|
Generates coverage via \f[C]gcov\f[R] and imports it. |
|
|
395 |
|
Generates coverage via \f[V]gcov\f[R] and imports it. |
382 |
396 |
.PP |
.PP |
383 |
|
\f[B]Usage: new-gcovi [options\&...] [covoutroot]\f[R] |
|
|
397 |
|
\f[B]Usage: new-gcovi [options\&...] |
|
398 |
|
[covoutroot]\f[R] |
384 |
399 |
.PP |
.PP |
385 |
400 |
\f[B]Parameters:\f[R] |
\f[B]Parameters:\f[R] |
386 |
401 |
.IP \[bu] 2 |
.IP \[bu] 2 |
|
... |
... |
Generates coverage via \f[C]gcov\f[R] and imports it. |
388 |
403 |
.PP |
.PP |
389 |
404 |
\f[B]Options:\f[R] |
\f[B]Options:\f[R] |
390 |
405 |
.IP \[bu] 2 |
.IP \[bu] 2 |
391 |
|
\f[B]-h [ \[en]help ]\f[R] \[en] display help message; |
|
|
406 |
|
\f[B]-h [ --help ]\f[R] \[en] display help message; |
392 |
407 |
.IP \[bu] 2 |
.IP \[bu] 2 |
393 |
|
\f[B]-v [ \[en]verbose ]\f[R] \[en] print output of external commands; |
|
|
408 |
|
\f[B]-v [ --verbose ]\f[R] \[en] print output of external commands; |
394 |
409 |
.IP \[bu] 2 |
.IP \[bu] 2 |
395 |
|
\f[B]-e [ \[en]exclude ] arg\f[R] \[en] specifies a path to exclude (can |
|
396 |
|
be repeated), paths are taken to be relative to the root of the |
|
397 |
|
repository; |
|
|
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; |
398 |
412 |
.IP \[bu] 2 |
.IP \[bu] 2 |
399 |
|
\f[B]\[en]prefix arg\f[R] \[en] prefix to be added to relative path of |
|
|
413 |
|
\f[B]--prefix arg\f[R] \[en] prefix to be added to relative path of |
400 |
414 |
sources; |
sources; |
401 |
415 |
.IP \[bu] 2 |
.IP \[bu] 2 |
402 |
|
\f[B]\[en]ref-name arg\f[R] \[en] forces custom ref name; |
|
|
416 |
|
\f[B]--ref-name arg\f[R] \[en] forces custom ref name; |
403 |
417 |
.IP \[bu] 2 |
.IP \[bu] 2 |
404 |
|
\f[B]-c [ \[en]capture-worktree ]\f[R] \[en] make a dangling commit if |
|
|
418 |
|
\f[B]-c [ --capture-worktree ]\f[R] \[en] make a dangling commit if |
405 |
419 |
working directory is dirty. |
working directory is dirty. |
406 |
420 |
.PP |
.PP |
407 |
|
To do its work this subcommand invokes \f[C]gcov\f[R] and then parses |
|
|
421 |
|
To do its work this subcommand invokes \f[V]gcov\f[R] and then parses |
408 |
422 |
its output in intermediate format, which is only mostly stable so usage |
its output in intermediate format, which is only mostly stable so usage |
409 |
|
with some versions of \f[C]gcov\f[R] might require changes. |
|
|
423 |
|
with some versions of \f[V]gcov\f[R] might require changes. |
410 |
424 |
.SS new-json |
.SS new-json |
411 |
425 |
.PP |
.PP |
412 |
426 |
Imports new build in JSON format from standard input. |
Imports new build in JSON format from standard input. |