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)
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.
8 2e3b39bc 2023-04-14 stsp 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.
13 13b2bc37 2022-10-23 stsp To compile the Got client tool suite on OpenBSD, run:
17 7cc94e29 2018-09-08 stsp $ make install
19 53ccebc2 2019-07-30 stsp This will install the following commands:
21 53ccebc2 2019-07-30 stsp got, the command line interface
22 53ccebc2 2019-07-30 stsp tog, an ncurses-based interactive Git repository browser
23 53ccebc2 2019-07-30 stsp several helper programs from the libexec directory
24 53ccebc2 2019-07-30 stsp man pages (only installed if building sources from a Got release tarball)
26 53ccebc2 2019-07-30 stsp A Got release tarball will install files under /usr/local by default.
27 53ccebc2 2019-07-30 stsp A build started in Got's Git repository will install files under ~/bin.
29 0e673013 2019-01-02 stsp Tests will pass only after 'make install' because they rely on installed
30 ef3dc9f3 2023-04-14 stsp binaries in $PATH. Any tests written as shell scripts also depend on git(1).
31 34c3415f 2021-09-21 stsp Tests which use the got clone, fetch, and send commands will fail if
32 34c3415f 2021-09-21 stsp 'ssh 127.0.0.1' does not succeed non-interactively.
34 c4096499 2019-01-02 stsp $ doas pkg_add git
35 7cc94e29 2018-09-08 stsp $ make regress
37 b32c4525 2020-01-05 stsp To test with packed repositories, run:
39 b32c4525 2020-01-05 stsp $ make regress GOT_TEST_PACK=1
41 c2f61165 2023-02-17 op To test with packed repositories using the ref-delta representation for
42 c2f61165 2023-02-17 op deltified objects, run:
44 c2f61165 2023-02-17 op $ make regress GOT_TEST_PACK=ref-delta
46 11f4fa81 2020-10-01 stsp Because got unveils the /tmp directory by default using the /tmp directory
47 11f4fa81 2020-10-01 stsp for test data can hide bugs. However, /tmp remains the default because
48 11f4fa81 2020-10-01 stsp there is no better alternative that works out of the box. In order to
49 11f4fa81 2020-10-01 stsp store test data in a directory other than /tmp, such as ~/got-test, run:
51 11f4fa81 2020-10-01 stsp $ mkdir ~/got-test
52 11f4fa81 2020-10-01 stsp $ make regress GOT_TEST_ROOT=~/got-test
54 ef3dc9f3 2023-04-14 stsp To run the tog automated test suite:
56 af21bb7e 2023-04-12 mark $ make tog-regress
58 af21bb7e 2023-04-12 mark Like Got, either individual tests or the entire suite can be run:
60 af21bb7e 2023-04-12 mark $ cd regress/tog
61 af21bb7e 2023-04-12 mark $ make # run all tests
62 af21bb7e 2023-04-12 mark $ ./log.sh # run log view tests
64 53ccebc2 2019-07-30 stsp Man page files in the Got source tree can be viewed with 'man -l':
66 107f9ed5 2019-07-27 klemens $ man -l got/got.1
67 107f9ed5 2019-07-27 klemens $ man -l got/git-repository.5
68 107f9ed5 2019-07-27 klemens $ man -l got/got-worktree.5
69 107f9ed5 2019-07-27 klemens $ man -l tog/tog.1
71 e1fa9f20 2019-07-14 stsp EXAMPLES in got.1 contains a quick-start guide for OpenBSD developers.
74 13b2bc37 2022-10-23 stsp To compile the Got server tool suite on OpenBSD, run:
77 13b2bc37 2022-10-23 stsp $ make server
78 13b2bc37 2022-10-23 stsp $ make server-install
80 13b2bc37 2022-10-23 stsp This will install the following commands:
82 13b2bc37 2022-10-23 stsp gotd, the repository server program
83 f1752522 2022-10-29 stsp gotctl, the server control utility
84 13b2bc37 2022-10-23 stsp gotsh, the login shell for users accessing the server via the network
85 b09c1279 2023-03-28 stsp gitwrapper, like mailwrapper(8) but for git-upload-pack and git-receive-pack
87 13b2bc37 2022-10-23 stsp See the following manual page files for information about server setup:
89 13b2bc37 2022-10-23 stsp $ man -l gotd/gotd.8
90 13b2bc37 2022-10-23 stsp $ man -l gotd/gotd.conf.5
91 f1752522 2022-10-29 stsp $ man -l gotctl/gotctl.8
92 13b2bc37 2022-10-23 stsp $ man -l gotsh/gotsh.1
93 b09c1279 2023-03-28 stsp $ man -l gitwrapper/gitwrapper.1
95 6ae16afd 2022-10-31 stsp See regress/gotd/README for information about running the server test suite.
98 0d8212e7 2022-12-30 stsp Game of Trees Web Daemon (gotwebd) is a FastCGI program which displays
99 0d8212e7 2022-12-30 stsp repository data and is designed to work with httpd(8).
101 06991378 2022-12-30 tracey To compile gotwebd on OpenBSD, run:
103 06991378 2022-12-30 tracey $ make webd
104 06991378 2022-12-30 tracey # make webd-install
106 270ebbdc 2020-01-16 stsp This will create the following files:
107 06991378 2022-12-30 tracey the daemon program /usr/local/sbin/gotwebd
108 06991378 2022-12-30 tracey css and image files in /var/www/htdocs/gotwebd
109 06991378 2022-12-30 tracey the gotwebd init script in /etc/rc.d
110 270ebbdc 2020-01-16 stsp man pages (only installed if building sources from a Got release tarball)
112 738b3756 2020-01-28 stsp Documentation is available in manual pages:
114 06991378 2022-12-30 tracey $ man -l gotwebd/gotwebd.8
115 06991378 2022-12-30 tracey $ man -l gotwebd/gotwebd.conf.5
118 296304f3 2021-06-18 stsp Got can be built with profiling enabled to debug performance issues.
119 296304f3 2021-06-18 stsp Note that profiled builds cannot make use of pledge(2).
120 296304f3 2021-06-18 stsp Profiling should only be enabled for one program at a time. Otherwise,
121 296304f3 2021-06-18 stsp multiple programs will attempt to write to the 'gmon.out' file in the
122 296304f3 2021-06-18 stsp current working directory.
124 296304f3 2021-06-18 stsp For example, to compile got-read-pack with profiling enabled:
126 296304f3 2021-06-18 stsp $ cd libexec/got-read-pack
127 296304f3 2021-06-18 stsp $ make clean
128 296304f3 2021-06-18 stsp $ make PROFILE=1
129 296304f3 2021-06-18 stsp $ make install
131 296304f3 2021-06-18 stsp Running any Got command which ends up using got-read-pack should now
132 296304f3 2021-06-18 stsp produce the file 'gmon.out' in the current working directory.
133 296304f3 2021-06-18 stsp The gprof2dot program can be used to generate a profile graph:
135 296304f3 2021-06-18 stsp $ doas pkg_add gprof2dot graphviz
136 296304f3 2021-06-18 stsp $ gprof ~/bin/got-read-pack gmon.out | gprof2dot | dot -T png > profile.png
139 42620da7 2019-07-14 stsp Guidelines for reporting problems:
141 42620da7 2019-07-14 stsp All problem/bug reports should include a reproduction recipe in form of a
142 42620da7 2019-07-14 stsp shell script which starts out with an empty repository and runs a series of
143 8deda1af 2019-07-14 stsp Got and/or Git commands to trigger the problem, be it a crash or some other
144 42620da7 2019-07-14 stsp undesirable behaviour.
146 42620da7 2019-07-14 stsp The regress/cmdline directory contains plenty of example scripts.
147 42620da7 2019-07-14 stsp An ideal reproduction recipe is written as an xfail ("expected failure")
148 42620da7 2019-07-14 stsp regression test. For a real-world example of an xfail test, see commits
149 42620da7 2019-07-14 stsp 4866d0842a2b34812818685aaa31d3e0a966412d and
150 8deda1af 2019-07-14 stsp 2b496619daecc1f25b1bc0c53e01685030dc2c74 in Got's history.
152 42620da7 2019-07-14 stsp Please take this request very seriously; Ask for help with writing your
153 42620da7 2019-07-14 stsp regression test before asking for your problem to be fixed. Time invested
154 42620da7 2019-07-14 stsp in writing a regression test saves time wasted on back-and-forth discussion
155 42620da7 2019-07-14 stsp about how the problem can be reproduced. A regression test will need to be
156 42620da7 2019-07-14 stsp written in any case to verify a fix and prevent the problem from resurfacing.
158 9532f6b4 2019-07-14 stsp It is also possible to write test cases in C. Various examples of this
159 7d405766 2019-07-30 stsp exist in the regress/ directory. Most such tests are unit tests; it is
160 7d405766 2019-07-30 stsp unlikely that a problem found during regular usage will require a test
161 7d405766 2019-07-30 stsp to be written in C.
163 56f95bee 2019-07-14 stsp Please always try to find a way to trigger your problem via the command line
164 56f95bee 2019-07-14 stsp interface before reporting a problem without a written test case included.
165 56f95bee 2019-07-14 stsp If writing an automated test really turns out to be impossible, please
166 56f95bee 2019-07-14 stsp explain in very clear terms how the problem can be reproduced.
168 3ba86cef 2019-09-25 stsp Mail problem reports to: gameoftrees@openbsd.org
171 42620da7 2019-07-14 stsp Guidelines for submitting patches:
173 3ba86cef 2019-09-25 stsp Mail patches to: gameoftrees@openbsd.org
174 52be27fc 2019-07-30 stsp Pull requests via any Git hosting sites will likely be overlooked.
175 52be27fc 2019-07-30 stsp Please keep the intended target audience in mind when contributing to Got.
178 3ba86cef 2019-09-25 stsp Subscribing to the gameoftrees@openbsd.org mailing list:
180 3ba86cef 2019-09-25 stsp The mailing list is used for patch reviews, bug reports, and user questions.
181 3ba86cef 2019-09-25 stsp To subscribe, send mail to majordomo@openbsd.org with a message body of:
182 3ba86cef 2019-09-25 stsp subscribe gameoftrees
184 3ba86cef 2019-09-25 stsp See https://www.openbsd.org/mail.html for more information.
