Diff options
Diffstat (limited to 'README.txt')
| -rw-r--r-- | README.txt | 174 |
1 file changed, 52 insertions, 122 deletions
@@ -33,85 +33,43 @@ This will install `cgit.cgi` and `cgit.css` into `/var/www/htdocs/cgit`. You can 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". +The only required library is zlib. cgit builds without OpenSSL or libcurl, so no +development packages for those are needed. + +Lua is optional and only powers the lua: filter extensions (the 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. To pin an implementation: $ make LUA_PKGCONFIG=lua5.4 +Acceptable LUA_PKGCONFIG values include "luajit", "lua", "lua5.4", "lua5.3", +"lua5.2" and "lua5.1". + To build without Lua, so the binary needs no Lua at runtime: $ make NO_LUA=1 -Previewing locally ------------------- - -cgit is a CGI program, so trying it out normally means configuring a web server. -For development there is a small dependency-free preview server at -`tools/serve.py` that runs the built binary and serves the static assets. It -needs only Python 3. - - $ python3 tools/serve.py --config /path/to/cgitrc --port 8080 - -It is a development aid and is not meant to face the internet. - - -Tests +Setup ----- -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 ------------- - -* zlib -* optional: luajit or lua, most reliably used when pkg-config is available +cgit is a CGI program. Complete, commented configurations for nginx, Apache and +lighttpd live in `custom/servers/`, each explaining how that server routes +requests to the binary and serves the static assets off disk. -cgit builds without OpenSSL or libcurl, so no development packages for those are -needed. +At runtime cgit reads `/etc/cgitrc` for its options and for the list of +repositories to display. A fully commented starting point with every option at +its default is in `custom/cgitrc`, and `MANUAL.txt` documents each option in +full. 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/` mostly need extra Lua modules, +and each script's header lists the exact install commands for its own. * The auth filters (`auth-file.lua`, `auth-inline.lua`) need `luaossl` and `luaposix`. @@ -119,20 +77,12 @@ script's header lists the exact install commands for its own dependencies. `luaossl`. * The syntax highlighter (`syntax-highlight.lua`) needs `lpeg` and a Scintillua lexer set. -* The about-page renderer (`about-render.lua`) needs `lpeg` for markdown and - man pages. Plain text needs only Lua. +* The about-page renderer (`about-render.lua`) needs `lpeg` for markdown and man + pages. Plain text needs only Lua. +* `link-commits.lua` needs nothing beyond Lua itself. -These filters target Lua 5.1 through 5.4 and LuaJIT. `luaossl` has no Lua 5.5 -build, so build cgit against 5.1 to 5.4 if you use the auth or email filters. -`link-commits.lua` needs nothing beyond Lua itself. - - -Web server configuration ------------------------- - -cgit is a CGI program. Complete, commented configurations for nginx, Apache and -lighttpd live in `custom/servers/`, each explaining how that server routes -requests to the binary and serves the static assets off disk. +`luaossl` has no Lua 5.5 build, so build cgit against 5.1 to 5.4 if you use the +auth or email filters. URLs and query parameters @@ -142,11 +92,7 @@ cgit serves every page from one CGI program, so a url names the repository, the page and a path inside that page. There are two forms and they carry the same information. With virtual-root set, a request is a path, written as /<repo>/<page>/<path> with anything else as a query string. Without it, the -whole request lives in the query string as ?url=<repo>/<page>/<path>, which is -the form the test suite uses. In the path form the first extra argument opens -the query string with a question mark, and in the url= form it continues the -existing one with an ampersand, which is why links in the two forms are spelled -differently. +whole request lives in the query string as ?url=<repo>/<page>/<path>. The page name is the second element and is one of about, atom, blame, blob, commit, diff, log, patch, plain, rawdiff, refs, snapshot, stats, summary, tag or @@ -160,27 +106,27 @@ plus decodes to a space. Every parameter is optional. The pages column names the pages that read each one, where a value of all marks the few not tied to particular pages. -+----------+----------------------+---------------------------------------------+ -| param | pages | description | -+----------+----------------------+---------------------------------------------+ -| url | all | repository, page and path in one value | -| h | all | the branch or ref to read | -| id | all | pin the page to one commit or object | -| id2 | diff patch rawdiff | the second object of a diff, paired with id | -| ofs | index log refs stats | offset into a paged listing | -| path | all | restrict the page to one path | -| q | log | the search term | -| qt | log | one of grep, author, committer or range | -| s | index | sort key for the listing | -| showmsg | log | show full commit messages | -| period | stats | the statistics window, one of w, m, q or y | -| dt | diff commit | diff type, unified, side by side or raw | -| ss | diff commit | shorthand for the side by side diff | -| all | atom | include every ref rather than one branch | -| context | diff commit | lines of context around a diff hunk | -| ignorews | diff commit | ignore whitespace when diffing | -| follow | log | follow a single path across renames | -+----------+----------------------+---------------------------------------------+ ++----------+----------------------+--------------------------------------------+ +| param | pages | description | ++----------+----------------------+--------------------------------------------+ +| url | all | repository, page and path in one value | +| h | all | the branch or ref to read | +| id | all | pin the page to one commit or object | +| id2 | diff patch rawdiff | second object of a diff, paired with id | +| ofs | index log refs stats | offset into a paged listing | +| path | all | restrict the page to one path | +| q | log | the search term | +| qt | log | one of grep, author, committer or range | +| s | index | sort key for the listing | +| showmsg | log | show full commit messages | +| period | stats | the statistics window, one of w, m, q or y | +| dt | diff commit | diff type, unified, side by side or raw | +| ss | diff commit | shorthand for the side by side diff | +| all | atom | include every ref rather than one branch | +| context | diff commit | lines of context around a diff hunk | +| ignorews | diff commit | ignore whitespace when diffing | +| follow | log | follow a single path across renames | ++----------+----------------------+--------------------------------------------+ 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 @@ -209,26 +155,10 @@ Some worked examples, in the url= form. ?url=demo/atom&h=main the commit feed for a branch -Runtime configuration ---------------------- - -The file `/etc/cgitrc` is read by cgit before handling a request. In addition to -runtime parameters, this file may also contain a list of repositories displayed -by cgit (see `MANUAL.txt` for further details). A fully commented starting point -with every option at its default is in `custom/cgitrc`. - - -The cache ---------- - -When cgit is invoked it looks for a cache file matching the request and returns -it to the client. If no such cache file exists (or if it has expired), the -content for the request is written into the proper cache file before the file is -returned. - -If the cache file has expired but cgit is unable to obtain a lock for it, the -stale cache file is returned to the client. This is done to favour page -throughput over page freshness. +Credits +------- -The generated content contains the complete response to the client, including -the HTTP headers. +cgit was created by Lars Hjemli and maintained upstream for many years, most +recently by Jason A. Donenfeld. This repository is an independent fork that +builds on their work. They are not maintainers of this fork and are not +responsible for it. |