Blame


1 c75df689 2019-07-14 stsp Game of Trees (Got) is a version control system which prioritizes ease
2 37486c75 2020-03-05 stsp of use and simplicity over flexibility (https://gameoftrees.org)
3 7cc94e29 2018-09-08 stsp
4 66164023 2019-08-09 stsp Got is still under development; it is being developed exclusively
5 66164023 2019-08-09 stsp on OpenBSD and its target audience are OpenBSD developers. Got is
6 66164023 2019-08-09 stsp ISC-licensed and was designed with pledge(2) and unveil(2) in mind.
7 dd2a8a69 2019-07-14 stsp
8 3682a04d 2023-04-14 thomas Got uses Git repositories to store versioned data. Git can be used
9 66164023 2019-08-09 stsp for any functionality which has not yet been implemented in Got.
10 66164023 2019-08-09 stsp It will always remain possible to work with both Got and Git on
11 66164023 2019-08-09 stsp the same repository.
12 66164023 2019-08-09 stsp
13 71641cee 2023-06-22 thomas A Got release tarball will install files under /usr/local by default.
14 71641cee 2023-06-22 thomas This default can be changed by passing PREFIX=/some/path to make.
15 71641cee 2023-06-22 thomas
16 71641cee 2023-06-22 thomas A build started in Got's Git repository will install files under ~/bin,
17 71641cee 2023-06-22 thomas which may have to be added to $PATH and be created first:
18 71641cee 2023-06-22 thomas
19 71641cee 2023-06-22 thomas $ mkdir ~/bin
20 71641cee 2023-06-22 thomas
21 3efd8e31 2022-10-23 thomas To compile the Got client tool suite on OpenBSD, run:
22 7cc94e29 2018-09-08 stsp
23 7cc94e29 2018-09-08 stsp $ make obj
24 7cc94e29 2018-09-08 stsp $ make
25 7cc94e29 2018-09-08 stsp $ make install
26 7cc94e29 2018-09-08 stsp
27 53ccebc2 2019-07-30 stsp This will install the following commands:
28 7cc94e29 2018-09-08 stsp
29 53ccebc2 2019-07-30 stsp got, the command line interface
30 53ccebc2 2019-07-30 stsp tog, an ncurses-based interactive Git repository browser
31 53ccebc2 2019-07-30 stsp several helper programs from the libexec directory
32 53ccebc2 2019-07-30 stsp man pages (only installed if building sources from a Got release tarball)
33 7cc94e29 2018-09-08 stsp
34 0e673013 2019-01-02 stsp Tests will pass only after 'make install' because they rely on installed
35 ffa5bcf7 2023-04-14 thomas binaries in $PATH. Any tests written as shell scripts also depend on git(1).
36 34c3415f 2021-09-21 stsp Tests which use the got clone, fetch, and send commands will fail if
37 34c3415f 2021-09-21 stsp 'ssh 127.0.0.1' does not succeed non-interactively.
38 7cc94e29 2018-09-08 stsp
39 9af9ce32 2024-04-25 thomas.ad Tests for HTTP protocol support rely on the HTTP::Daemon Perl module.
40 9af9ce32 2024-04-25 thomas.ad
41 9af9ce32 2024-04-25 thomas.ad $ doas pkg_add git p5-http-daemon
42 7cc94e29 2018-09-08 stsp $ make regress
43 7cc94e29 2018-09-08 stsp
44 b32c4525 2020-01-05 stsp To test with packed repositories, run:
45 b32c4525 2020-01-05 stsp
46 b32c4525 2020-01-05 stsp $ make regress GOT_TEST_PACK=1
47 b32c4525 2020-01-05 stsp
48 9581acf4 2023-02-17 thomas To test with packed repositories using the ref-delta representation for
49 9581acf4 2023-02-17 thomas deltified objects, run:
50 9581acf4 2023-02-17 thomas
51 9581acf4 2023-02-17 thomas $ make regress GOT_TEST_PACK=ref-delta
52 9581acf4 2023-02-17 thomas
53 f034749e 2024-08-08 thomas To test with sha256 object IDs instead of sha1, run:
54 f034749e 2024-08-08 thomas
55 f034749e 2024-08-08 thomas $ make regress GOT_TEST_ALGO=sha256
56 f034749e 2024-08-08 thomas
57 f034749e 2024-08-08 thomas The GOT_TEST_PACK and GOT_TEST_ALGO flags can be combined to test packed
58 f034749e 2024-08-08 thomas repositories with sha256 object IDs.
59 f034749e 2024-08-08 thomas
60 11f4fa81 2020-10-01 stsp Because got unveils the /tmp directory by default using the /tmp directory
61 11f4fa81 2020-10-01 stsp for test data can hide bugs. However, /tmp remains the default because
62 11f4fa81 2020-10-01 stsp there is no better alternative that works out of the box. In order to
63 11f4fa81 2020-10-01 stsp store test data in a directory other than /tmp, such as ~/got-test, run:
64 11f4fa81 2020-10-01 stsp
65 11f4fa81 2020-10-01 stsp $ mkdir ~/got-test
66 11f4fa81 2020-10-01 stsp $ make regress GOT_TEST_ROOT=~/got-test
67 11f4fa81 2020-10-01 stsp
68 59d2cb90 2023-04-22 thomas The tog automated test suite is also run with 'make regress'.
69 59d2cb90 2023-04-22 thomas Like Got, however, individual tests or the entire suite can be run:
70 b85a3496 2023-04-14 thomas
71 b85a3496 2023-04-14 thomas $ cd regress/tog
72 b85a3496 2023-04-14 thomas $ make # run all tests
73 b85a3496 2023-04-14 thomas $ ./log.sh # run log view tests
74 b85a3496 2023-04-14 thomas
75 53ccebc2 2019-07-30 stsp Man page files in the Got source tree can be viewed with 'man -l':
76 7cc94e29 2018-09-08 stsp
77 107f9ed5 2019-07-27 klemens $ man -l got/got.1
78 107f9ed5 2019-07-27 klemens $ man -l got/git-repository.5
79 107f9ed5 2019-07-27 klemens $ man -l got/got-worktree.5
80 107f9ed5 2019-07-27 klemens $ man -l tog/tog.1
81 42620da7 2019-07-14 stsp
82 e1fa9f20 2019-07-14 stsp EXAMPLES in got.1 contains a quick-start guide for OpenBSD developers.
83 42620da7 2019-07-14 stsp
84 738b3756 2020-01-28 stsp
85 3efd8e31 2022-10-23 thomas To compile the Got server tool suite on OpenBSD, run:
86 3efd8e31 2022-10-23 thomas
87 3efd8e31 2022-10-23 thomas $ make obj
88 3efd8e31 2022-10-23 thomas $ make server
89 3efd8e31 2022-10-23 thomas $ make server-install
90 3efd8e31 2022-10-23 thomas
91 3efd8e31 2022-10-23 thomas This will install the following commands:
92 3efd8e31 2022-10-23 thomas
93 3efd8e31 2022-10-23 thomas gotd, the repository server program
94 c902213d 2022-10-29 thomas gotctl, the server control utility
95 3efd8e31 2022-10-23 thomas gotsh, the login shell for users accessing the server via the network
96 5dcb3a43 2023-04-01 thomas gitwrapper, like mailwrapper(8) but for git-upload-pack and git-receive-pack
97 3efd8e31 2022-10-23 thomas
98 3efd8e31 2022-10-23 thomas See the following manual page files for information about server setup:
99 3efd8e31 2022-10-23 thomas
100 3efd8e31 2022-10-23 thomas $ man -l gotd/gotd.8
101 3efd8e31 2022-10-23 thomas $ man -l gotd/gotd.conf.5
102 c902213d 2022-10-29 thomas $ man -l gotctl/gotctl.8
103 3efd8e31 2022-10-23 thomas $ man -l gotsh/gotsh.1
104 5dcb3a43 2023-04-01 thomas $ man -l gitwrapper/gitwrapper.1
105 3efd8e31 2022-10-23 thomas
106 f2900386 2022-10-31 thomas See regress/gotd/README for information about running the server test suite.
107 3efd8e31 2022-10-23 thomas
108 f2900386 2022-10-31 thomas
109 2e4e6f2c 2023-01-02 thomas Game of Trees Web Daemon (gotwebd) is a FastCGI program which displays
110 2e4e6f2c 2023-01-02 thomas repository data and is designed to work with httpd(8).
111 e1fa9f20 2019-07-14 stsp
112 85c360aa 2023-01-02 thomas To compile gotwebd on OpenBSD, run:
113 270ebbdc 2020-01-16 stsp
114 85c360aa 2023-01-02 thomas $ make webd
115 85c360aa 2023-01-02 thomas # make webd-install
116 270ebbdc 2020-01-16 stsp
117 270ebbdc 2020-01-16 stsp This will create the following files:
118 85c360aa 2023-01-02 thomas the daemon program /usr/local/sbin/gotwebd
119 85c360aa 2023-01-02 thomas css and image files in /var/www/htdocs/gotwebd
120 85c360aa 2023-01-02 thomas the gotwebd init script in /etc/rc.d
121 270ebbdc 2020-01-16 stsp man pages (only installed if building sources from a Got release tarball)
122 270ebbdc 2020-01-16 stsp
123 738b3756 2020-01-28 stsp Documentation is available in manual pages:
124 270ebbdc 2020-01-16 stsp
125 85c360aa 2023-01-02 thomas $ man -l gotwebd/gotwebd.8
126 85c360aa 2023-01-02 thomas $ man -l gotwebd/gotwebd.conf.5
127 270ebbdc 2020-01-16 stsp
128 386c230c 2024-11-27 thomas The gotwebd test suite must be started as root in order to start and stop
129 386c230c 2024-11-27 thomas the gotwebd daemon. With the gotwebd binary installed, the test suite can
130 386c230c 2024-11-27 thomas be run from the top-level directory:
131 270ebbdc 2020-01-16 stsp
132 a93fc19c 2024-11-27 thomas $ doas make webd-regress
133 386c230c 2024-11-27 thomas
134 386c230c 2024-11-27 thomas The test suite switches to non-root users as appropriate.
135 386c230c 2024-11-27 thomas
136 386c230c 2024-11-27 thomas
137 296304f3 2021-06-18 stsp Got can be built with profiling enabled to debug performance issues.
138 296304f3 2021-06-18 stsp Note that profiled builds cannot make use of pledge(2).
139 296304f3 2021-06-18 stsp Profiling should only be enabled for one program at a time. Otherwise,
140 296304f3 2021-06-18 stsp multiple programs will attempt to write to the 'gmon.out' file in the
141 296304f3 2021-06-18 stsp current working directory.
142 296304f3 2021-06-18 stsp
143 296304f3 2021-06-18 stsp For example, to compile got-read-pack with profiling enabled:
144 296304f3 2021-06-18 stsp
145 296304f3 2021-06-18 stsp $ cd libexec/got-read-pack
146 296304f3 2021-06-18 stsp $ make clean
147 296304f3 2021-06-18 stsp $ make PROFILE=1
148 296304f3 2021-06-18 stsp $ make install
149 296304f3 2021-06-18 stsp
150 296304f3 2021-06-18 stsp Running any Got command which ends up using got-read-pack should now
151 296304f3 2021-06-18 stsp produce the file 'gmon.out' in the current working directory.
152 296304f3 2021-06-18 stsp The gprof2dot program can be used to generate a profile graph:
153 296304f3 2021-06-18 stsp
154 296304f3 2021-06-18 stsp $ doas pkg_add gprof2dot graphviz
155 296304f3 2021-06-18 stsp $ gprof ~/bin/got-read-pack gmon.out | gprof2dot | dot -T png > profile.png
156 296304f3 2021-06-18 stsp
157 296304f3 2021-06-18 stsp
158 42620da7 2019-07-14 stsp Guidelines for reporting problems:
159 42620da7 2019-07-14 stsp
160 42620da7 2019-07-14 stsp All problem/bug reports should include a reproduction recipe in form of a
161 42620da7 2019-07-14 stsp shell script which starts out with an empty repository and runs a series of
162 8deda1af 2019-07-14 stsp Got and/or Git commands to trigger the problem, be it a crash or some other
163 42620da7 2019-07-14 stsp undesirable behaviour.
164 42620da7 2019-07-14 stsp
165 42620da7 2019-07-14 stsp The regress/cmdline directory contains plenty of example scripts.
166 42620da7 2019-07-14 stsp An ideal reproduction recipe is written as an xfail ("expected failure")
167 42620da7 2019-07-14 stsp regression test. For a real-world example of an xfail test, see commits
168 42620da7 2019-07-14 stsp 4866d0842a2b34812818685aaa31d3e0a966412d and
169 8deda1af 2019-07-14 stsp 2b496619daecc1f25b1bc0c53e01685030dc2c74 in Got's history.
170 42620da7 2019-07-14 stsp
171 42620da7 2019-07-14 stsp Please take this request very seriously; Ask for help with writing your
172 42620da7 2019-07-14 stsp regression test before asking for your problem to be fixed. Time invested
173 42620da7 2019-07-14 stsp in writing a regression test saves time wasted on back-and-forth discussion
174 42620da7 2019-07-14 stsp about how the problem can be reproduced. A regression test will need to be
175 42620da7 2019-07-14 stsp written in any case to verify a fix and prevent the problem from resurfacing.
176 42620da7 2019-07-14 stsp
177 9532f6b4 2019-07-14 stsp It is also possible to write test cases in C. Various examples of this
178 7d405766 2019-07-30 stsp exist in the regress/ directory. Most such tests are unit tests; it is
179 7d405766 2019-07-30 stsp unlikely that a problem found during regular usage will require a test
180 7d405766 2019-07-30 stsp to be written in C.
181 9532f6b4 2019-07-14 stsp
182 56f95bee 2019-07-14 stsp Please always try to find a way to trigger your problem via the command line
183 56f95bee 2019-07-14 stsp interface before reporting a problem without a written test case included.
184 56f95bee 2019-07-14 stsp If writing an automated test really turns out to be impossible, please
185 56f95bee 2019-07-14 stsp explain in very clear terms how the problem can be reproduced.
186 42620da7 2019-07-14 stsp
187 3ba86cef 2019-09-25 stsp Mail problem reports to: gameoftrees@openbsd.org
188 42620da7 2019-07-14 stsp
189 42620da7 2019-07-14 stsp
190 42620da7 2019-07-14 stsp Guidelines for submitting patches:
191 42620da7 2019-07-14 stsp
192 3ba86cef 2019-09-25 stsp Mail patches to: gameoftrees@openbsd.org
193 52be27fc 2019-07-30 stsp Pull requests via any Git hosting sites will likely be overlooked.
194 52be27fc 2019-07-30 stsp Please keep the intended target audience in mind when contributing to Got.
195 3ba86cef 2019-09-25 stsp
196 3ba86cef 2019-09-25 stsp
197 3ba86cef 2019-09-25 stsp Subscribing to the gameoftrees@openbsd.org mailing list:
198 3ba86cef 2019-09-25 stsp
199 3ba86cef 2019-09-25 stsp The mailing list is used for patch reviews, bug reports, and user questions.
200 3ba86cef 2019-09-25 stsp To subscribe, send mail to majordomo@openbsd.org with a message body of:
201 3ba86cef 2019-09-25 stsp subscribe gameoftrees
202 3ba86cef 2019-09-25 stsp
203 3ba86cef 2019-09-25 stsp See https://www.openbsd.org/mail.html for more information.