Diff options
Diffstat (limited to 'README.txt')
| -rw-r--r-- | README.txt | 117 |
1 file changed, 65 insertions, 52 deletions
@@ -34,10 +34,10 @@ configure this location (and a few other things) by providing a `cgit.conf` file (see the Makefile for details). Lua is optional and only powers the lua: filter extensions (authentication, -email and commit-message filters in custom/extensions/). A plain build auto-detects a -Lua through pkg-config, preferring LuaJIT, and falls back to a Lua-less binary -when none is found. Acceptable values are generally "luajit", "lua", "lua5.4", -"lua5.3", "lua5.2" and "lua5.1". +email and commit-message filters in custom/extensions/). A plain build +auto-detects a Lua through pkg-config, preferring LuaJIT, and falls back to a +Lua-less binary when none is found. Acceptable values are generally "luajit", +"lua", "lua5.4", "lua5.3", "lua5.2" and "lua5.1". To pin an implementation: @@ -61,6 +61,42 @@ needs only Python 3. It is a development aid and is not meant to face the internet. +Tests +----- + +The suite in tests/ is built on the test library in the bundled Git tree, the +same harness Git uses for its own suite, one self-contained tNNNN-*.sh script +per area. Run it from the top level, which builds cgit and the bundled Git +tree before anything runs. + + $ make test + +Once those are built, a single script runs directly from tests/, where -v +shows each check and -i stops at the first failure. The full option list +lives in vendor/git/t/README, and options for a run through make go in +CGIT_TEST_OPTS, where --valgrind runs every cgit invocation under valgrind. + + $ cd tests && ./t0104-tree.sh -v + +The numbering walks outward, t000x for the ground the suite stands on, t01xx +for page content, t02xx for features that cut across pages, t03xx for +security regressions, t04xx for the helper tools under tools/ and t05xx for +the extensions under custom/extensions, each pairing unit checks under a +standalone Lua with a run through cgit itself. A failing script leaves its +trash directory behind under tests/trash/ with the pages it was looking at, and +scripts skip rather than fail when a helper program or Lua module is missing, +saying so in their output. + +A new script takes the next free number, needs the executable bit and is +picked up with no further wiring. Three traps are worth knowing. The cgitrc +that tests/setup.sh writes enables the cache, so a test rendering one URL +under two configs needs a config of its own with cache-size=0. A bare plus in +a cgit_url argument decodes to a space, so the foo+bar fixture repository is +written foo%2bbar. And a log page echoes the search query back inside an +input value, so an assertion that a commit is absent should match the subject +link, written as ">commit 2</a>", rather than the bare text. + + Dependencies ------------ @@ -74,8 +110,8 @@ needed. Filter extensions ----------------- -The optional Lua filters in `custom/extensions/` need extra Lua modules. Each script's -header lists the exact install commands for its own dependencies. +The optional Lua filters in `custom/extensions/` need extra Lua modules. Each +script's header lists the exact install commands for its own dependencies. * The auth filters (`auth-file.lua`, `auth-inline.lua`) need `luaossl` and `luaposix`. @@ -123,25 +159,28 @@ plus decodes to a space. These parameters are accepted, all of them optional. - url repository, page and path in one value, used instead of the - path form - h the branch or ref to read, defaulting to the repository default - id pin the page to one commit or object, which every page that - shows history honours - id2 the second object for a diff, so id and id2 name the two sides - ofs offset into a paged listing, used by log, refs and stats - path restrict the page to one path, equivalent to the trailing path - q the search term - qt what to search, one of grep, author, committer or range - s sort key on the index and refs pages - showmsg show full commit messages in a log listing - period the statistics window, one of w, m, q or y - dt diff type, selecting unified, side by side or raw - ss shorthand for the side by side diff - all include every ref rather than one branch, used by atom - context lines of context in a diff - ignorews ignore whitespace when diffing - follow follow a single path across renames in a log + url repository, page and path in one value, used instead of + the path form + h the branch or ref to read, defaulting to the repository + default + id pin the page to one commit or object, which every page + that shows history honours + id2 the second object for a diff, so id and id2 name the + two sides + ofs offset into a paged listing, used by log, refs and stats + path restrict the page to one path, equivalent to the + trailing path + q the search term + qt what to search, one of grep, author, committer or range + s sort key on the index and refs pages + showmsg show full commit messages in a log listing + period the statistics window, one of w, m, q or y + dt diff type, selecting unified, side by side or raw + ss shorthand for the side by side diff + all include every ref rather than one branch, used by atom + context lines of context in a diff + ignorews ignore whitespace when diffing + follow follow a single path across renames in a log A few endpoints are not ordinary pages. The snapshot page takes a filename rather than a ref, so /demo/snapshot/demo-1.0.tar.gz names both the ref and the @@ -164,6 +203,7 @@ Some worked examples, in the url= form. ?url=demo/plain/README.md the raw bytes of one file ?url=demo/atom&h=main the commit feed for a branch + Runtime configuration --------------------- @@ -173,33 +213,6 @@ by cgit (see `cgitrc.5.txt` for further details). A fully commented starting point with every option at its default is in `custom/cgitrc`. -Securing an instance --------------------- - -A public instance needs a few deliberate choices, all set in cgitrc and -documented in `cgitrc.5.txt`. - -* Keep private repositories out of `scan-path`, or set `strict-export` to a - marker filename so only repositories that contain it are published. - -* Gate the whole instance behind a login with `auth-filter`. Two example filters - ship in `custom/extensions/`, `auth-inline.lua` and `auth-file.lua`. - -* Terminate TLS at the web server in front of cgit. - -* The example configs in `custom/servers/` set a Content-Security-Policy and - related headers at the web server, where they also cover the static assets. - -* `max-blob-size` bounds how much a single request reads into memory, and - defaults to 10 MB. - -* Leave `enable-cache-list` off, since it exposes the cache path and the URLs - other visitors requested. - -* Build the deployed binary with the hardening flags via - `tools/release-build.sh`. - - The cache --------- |