4 This is the portable version of got[1] (Game of Trees), using autotools to
5 provide the library checks required for GoT's dependencies.
7 The following operating systems are supported:
18 Note that the names of these libraries are indicative only; the names might
23 * `libncurses` (for tog(1))
24 * `libbsd` (BSD's arc4random routines)
25 * `libmd` (SHA256 routines)
26 * `libuuid` (for UUID generation)
27 * `libz` (for Z compression)
28 * `pkg-config` (for searching libraries)
29 * `bison` (for configuration file grammar)
30 * `libevent` (for gotwebd)
31 * `libtls` (may be known as `libretls`)
38 * `libevent` (for gotwebd)
45 * `libevent` (for gotwebd)
53 * `libevent` (for gotwebd)
64 * `libevent` (for gotwebd)
70 To run the test suite:
76 The tests depend on git and the HTTP::Daemon Perl module.
78 Got may have to be installed system-wide before the tests will run
79 successfully because paths to helper programs, such as got-read-pack,
80 are hard-coded in user-facing binaries, such as got and tog.
82 Operations such as clone and send which use the network will be trying to
83 connect to 127.0.0.1 over ssh, as the same user who invoked 'make tests'.
84 The command 'ssh 127.0.0.1' must succeed without any interactive prompting.
85 The host key may need to be manually accepted once before running tests.
86 An SSH key can be installed in ~/.ssh/authorized_keys for authentication.
88 The OpenBSD version of Got also has tests for gotd and gotwebd.
89 These tests cannot be run in -portable yet.
91 There are environment variables which control some test parameters:
93 GOT_TEST_PACK=1 will force tests to use pack files instead of loose
94 objects. GOT_TEST_PACK=ref-delta will force use of pack files with
95 ref-deltas rather than offset-deltas.
97 GOT_TEST_ALGO=sha256 will run tests with sha256 repositories.
99 GOT_TEST_ROOT can be set to a path where temporary test data gets stored.
100 This defaults to /tmp.
107 NOTE: THIS ONLY WORKS AFTER `make install` DUE TO HOW PATHS TO LIBEXEC
108 HELPERS ARE HARD-CODED INTO THE BINARIES.
115 $ ./configure && make
119 INSTALLING AND PACKAGING GITWRAPPER
120 ===================================
122 The gotd server has an optional companion tool called gitwrapper.
124 A gotd server can be used without gitwrapper in the following cases:
126 1) The Git client's user account has gotsh configured as its login shell.
128 2) The Git client's user account sees gotsh installed under the names
129 git-receive-pack and git-upload-pack, and these appear in $PATH before
130 the corresponding Git binaries if Git is also installed. Setting up the
131 user's $PATH in this way can require the use of SetEnv in sshd_config.
133 The above cases can be too restrictive. For example, users who have regular
134 shell access to the system may expect to be able to serve Git repositories
135 from their home directories while also accessing repositories served by gotd.
137 Once gitwrapper has been installed correctly it provides an out-of-the box
138 experience where both gotd and Git "just work".
139 However, this will require coordination with the system's Git installation
140 and/or distribution package because the names of two specific Git programs
141 will be overlapping: git-upload-pack and git-receive-pack
143 If the gitwrapper tool will be used then it must replace git-receive-pack
144 and git-upload-pack in /usr/bin. This is usually achieved by replacing the
145 regular Git binaries in /usr/bin with symlinks to gitwrapper:
148 -rwxr-xr-x 1 root root 1019928 Aug 24 00:16 /usr/bin/gitwrapper
149 lrwxrwxrwx 1 root root 10 Aug 20 12:40 /usr/bin/git-receive-pack -> gitwrapper
150 lrwxrwxrwx 1 root root 10 Aug 20 12:40 /usr/bin/git-upload-pack -> gitwrapper
153 The Git binaries remain available in Git's libexec directory, which is set
154 when Git gets compiled. On Debian it defaults to /usr/lib/git-core.
155 This same path must be given to Got's configure script at build time to
156 allow gitwrapper to find Git's binaries:
159 ./configure --with-gitwrapper-git-libexec-path=/usr/lib/git-core
162 Once gitwrapper is found in /usr/bin under the names git-receive-pack and
163 git-upload-pack, any Git repositories listed in /etc/gotd.conf will be
164 automatically served by gotd, and any Git repositories not listed in
165 /etc/gotd.conf will be automatically served by regular Git's git-upload-pack
166 and git-receive-pack. The client's login shell or $PATH no longer matter,
167 and a peaceful co-existence of gotd and Git is possible.
169 We recommend that distribution packagers take appropriate steps to package
170 gitwrapper as a required dependency of gotd. It is also possible to install
171 gitwrapper without installing gotd. As long as /etc/gotd.conf does not exist
172 or no repositories are listed in /etc/gotd.conf there will be no visible
173 change in run-time behaviour for Git users since gitwrapper will simply run
174 the standard Git tools.
175 In the OpenBSD ports tree both the regular git package and the gotd package
176 are depending on gitwrapper, and the git package no longer installs the
177 git-receive-pack and git-upload-pack programs in /usr/local/bin.
179 BRANCHES + SUBMITTING PATCHES
180 =============================
182 `got-portable` has two key branches:
184 * `main` which tracks got upstream untainted.
185 * `portable` which provides the portable version of GoT based from code on `main`
187 Patches for portable code fixes should be based from the `portable` branch and
188 sent to the mailing list for review [2] or sent to me directly (see CONTACT).
190 Portable-specific patches should have a shortlog in the form of:
193 portable: AREA: description
196 Where `AREA` relates to the change in question (for example, `regress`,
197 `libexec`, etc). In some cases, this can be omitted if it's a generic change.
199 This helps to delineate `-portable` changes from upstream `got`.
201 The read-only Github repository also runs CI checks using Cirrus-CI on Linux
204 SYNCING UPSTREAM CHANGES WITH PORTABLE
205 ======================================
207 The `-portable` GoT repository uses the following workflow:
210 Github (gh) GoT (upstream)
216 +--------> GoT-portable <------+
220 Here, `got-portable` is a clone of the `-portable` repository, locally on
221 disk. There are two remotes set up within that repository, via `git-remote`:
223 * `upstream` -- which points to the official GoT repository;
224 * `gh` -- which points to the mirrored `-portable` repository so that CI can
225 be run for cross-platform/test purposes [3]
226 * `origin` -- our cloned copy from `-portable`
228 Within the `-portable` repository are two key branches (there may be other
229 topic branches which represent on-going work):
231 * `main` -- this is the branch that tracks (without modification) those
232 changes from `upstream`. This branch is continually reset to
233 `upstream/main` whenever changes occur.
235 * `portable` -- this is the *default* branch of the `-portable` repository which
236 contains portable-specific changes to make `GoT` compile across different
239 When updating `-portable` from upstream changes, the following actions happen:
241 1. Changes from `upstream` are fetched. If there are no new changes, there's
243 2. Changes from `gh` are fetch so that the result can be pushed out to `gh`.
244 3. The difference between the local copy of `main` and `origin/main` is used
245 to represent the set of commits which have *NOT* yet been merged to
247 4. A topic-branch called `syncup` is created from the HEAD of the `portable`
248 branch to hold the to-be-cherry-picked commits from step 3.
249 5. These commits are then cherry-picked to the `syncup` branch.
250 6. If there's any conflicts, they must be resolved.
251 7. Once done, a sanity build is done in-situ to check there's nothing amiss.
252 8. If that succeeds, the `syncup` branch is merged to `portable` and pushed to
253 `gh` for verification against CI.
254 9. If that fails, fixes continue and pushed up to `gh` as required.
255 10. Once happy, both the `main` and `portable` branches can be merged to `origin`.
257 These steps are encapsulated in a script within `-portable`. [Link](../maintscripts/sync-upstream.sh)
259 RELEASING A NEW VERSION
260 =======================
262 Release for `-portable` try and align as close to upstream GoT as much as
263 possible, even on the same day where that can happen. That being said,
264 sometimes a release of `-portable` might happen outside of that cadence, where
265 a `-portable`-specific issue needs addressing, for example.
267 Before creating a new release, check the version of GoT as found in
268 `util/got-portable-ver.sh` -- as `GOT_PORTABLE_VER`:
271 GOT_PORTABLE_VER=0.75
275 Here, the *to be released* version of `got-portable` will be `0.75`.
276 Typically, this version is incremented directly after a release, such that
277 there's no need to change this value. The only exception would be if there
278 were an out-of-band release to `-portable`. In such cases, that would take
285 Where the suffix of `1`, `2`, etc., can be used to denote any sub-releases
286 from the `0.75` version.
288 The variable `GOT_RELEASE` needs be changed to `yes` so that the
289 GOT_PORTABLE_VER is asserted correctly.
291 Once the version is verified, the following should be run from the `portable`
292 branch -- and the repository should not have any outstanding modifications to
296 make clean ; ./autogen && ./configure && make distcheck
299 If this succeeds, the tarball is in the CWD, as: `got-portable-VERSION.tar.gz`
301 This can then be copied to the `got-www` repository and uploaded, along with
302 changing a couple of HTML pages therein to represent the new released version.
303 Additionally, the CHANGELOG file can be copied to the `got-www` and committed.
305 Once all of that has been done, the repository should be tagged to indicate
312 This can then be pushed out to `gh` and `origin`.
314 After that point, the version of `GOT_PORTABLE_VER` in
315 `util/got-portable-ver.sh` should be changed to the next version, and
316 `GOT_RELEASE` should be setg back to `no`.
321 * configure.ac should start defining AC_ENABLE arguments to allow for
322 finer-grained control of where to search for includes/libraries, etc.
323 * review the compat/ code. Some of those functions are probably picked up in
324 libbsd, so we should drop such implementations from compat/ where there's
325 overlap between libbsd and what's natively available.
330 Thomas Adam <thomas@xteddy.org><br />
331 thomas_adam (#gameoftrees on irc.libera.chat)
333 [1] https://gameoftrees.org<br />
334 [2] https://lists.openbsd.org/cgi-bin/mj_wwwusr?user=&passw=&func=lists-long-full&extra=gameoftrees
335 [3] https://github.com/ThomasAdam/got-portable
