Fold the test README and .gitignore into the root

1 file changed, 65 insertions, 52 deletions

diff --git a/README.txt b/README.txtindex b5c11b5..54dbcae 100644--- a/README.txt+++ b/README.txt@@ -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 --------- 
diff --git a/README.txt b/README.txt
index b5c11b5..54dbcae 100644
--- a/README.txt
+++ b/README.txt
@@ -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
 ---------