@@ -0,0 +1,63 @@
1+# xonecas.io
2+
3+My projects and their git history, as a static site. It reads git repos and renders `public/`, which any static
4+server can host, including the `<name>.git` folders you `git clone` from.
5+
6+```
7+ bin/site remote new ─► git push ─► repos/xonecas.io/<name>.git ──┐
8+ ├─► site index ─► site build ─► public/
9+ sources.txt ─► site import ─► repos/<host>/<owner>/<repo>.git ───┤
10+ overrides.txt ──┘
11+```
12+
13+## Start
14+
15+```sh
16+make site # builds bin/site
17+make import # mirrors every repo in sources.txt into repos/
18+make index # reads repos/ into data/projects.json
19+make serve # builds public/ and serves it on http://vm:8080
20+```
21+
22+Run everything from this folder. `bin/site help` lists the commands, and `bin/site <command> -h` lists a command's flags.
23+
24+## Manage repos
25+
26+| To | Run |
27+| --- | --- |
28+| Start a repo the site hosts | `bin/site remote new my-thing`, then the `git remote add` line it prints, then `git push -u origin main` |
29+| Show a repo you already have | `bin/site remote add ~/code/other-thing` (a path) or `bin/site remote add https://host/owner/repo.git` |
30+| Stop showing a repo | `bin/site remote rm <path or url>` (a hosted repo's data is kept) |
31+| List the repos | `bin/site remote list` |
32+| Fetch every added repo again | `make import` |
33+| Rebuild the site | `make index build` |
34+
35+A push to a hosted repo rebuilds `public/` by itself; its log is `repos/xonecas.io/<name>.git/build.log`.
36+After `remote add` or `rm`, run `make index build`.
37+
38+`repos/` is git-ignored. On the VM it is lost when the VM is recreated, so host repos on the machine that serves the site.
39+
40+## Fix how a project shows
41+
42+Edit `overrides.txt`, one rule per line, then `make index build`:
43+
44+```
45+merge <remote URL> <remote URL> make two remotes one project
46+rename <name> <new name> rename a project
47+hide <name> hide a project
48+show <name> list a fork or an empty repo, which are hidden by default
49+tag <name> +frontend -backend add or drop tags
50+```
51+
52+## Layout
53+
54+| Path | Holds |
55+| --- | --- |
56+| `cmd/site` | the `site` command: import, remote, index, build, serve, help |
57+| `internal/store` | the repo store: `sources.txt`, mirrors, hosted repos, the hosts' metadata |
58+| `internal/project` | groups repos into projects, and their tags, description and overrides |
59+| `internal/site` | renders every page into `public/` |
60+| `internal/repo` | runs git against a bare repo |
61+| `tickets/` | the Rats board |
62+
63+`make test` runs the tests.