1 # xgit 2 3 **Author:** [polymath](mailto:polymath@localhost) 4 **License:** BSD 2-Clause 5 6 `xgit` is its own standalone Python project: a static git page generator 7 (inspired by [stagit](https://git.codemadness.org/stagit/)). Point it at git 8 repositories (local demos or remotes), and it builds a browsable site — commit 9 logs, files, refs, Markdown, syntax-colored code, author profiles, and stats. 10 11 ``` 12 xgit/ ← this repository (the product) 13 ├── build serve sync demo ← run from here 14 ├── config.toml ← which repos to publish 15 ├── xgit/ ← Python package 16 ├── LICENSE README.md pyproject.toml 17 ├── data/ (generated, gitignored) 18 └── html/ (generated, gitignored) 19 ``` 20 21 ## Requirements 22 23 - Python 3.10+ 24 - `git` on your `PATH` 25 - No pip dependencies 26 27 ## Quick start 28 29 ```bash 30 cd /path/to/xgit # this repository root 31 chmod +x build serve sync demo # once 32 ./demo # seed 2 demos → build → serve :3121 33 ``` 34 35 Open **http://127.0.0.1:3121/** 36 37 You should see two demo repos: **hello** and **notes** (both by polymath). 38 39 ## Run files (project root) 40 41 | Command | Purpose | 42 |---------|---------| 43 | `./demo` | Wipe generated data, seed demos, fetch, build, serve | 44 | `./sync` | Seed demos if needed + fetch remotes + build `html/` | 45 | `./build` | Generate static pages only (`./build --fetch` to update remotes first) | 46 | `./serve` | Build then serve on `0.0.0.0:3121` | 47 | `./serve --no-build` | Serve existing `html/` without rebuilding | 48 | `config.toml` | Site name, ports/URLs, and **repository list** | 49 50 Same via module API: 51 52 ```bash 53 python -m xgit seed 54 python -m xgit sync 55 python -m xgit build 56 python -m xgit serve --port 3121 57 ``` 58 59 ## Adding remote git repositories 60 61 1. Edit **`config.toml`** in this repo’s root. 62 2. Add a `[[repos]]` block with a clone URL. 63 3. Run `./sync` (clones/updates mirrors under `data/repos/`, rebuilds `html/`). 64 4. Open or refresh the site (`./serve --no-build` if the server is already up). 65 66 ### HTTPS (GitHub / GitLab / Codeberg / …) 67 68 ```toml 69 [[repos]] 70 name = "myproject" 71 url = "https://github.com/you/myproject.git" 72 description = "short description" 73 owner = "polymath" 74 ``` 75 76 ### `git://` protocol 77 78 ```toml 79 [[repos]] 80 name = "sbase" 81 url = "git://git.suckless.org/sbase" 82 description = "suckless unix tools" 83 owner = "suckless" 84 ``` 85 86 ### SSH 87 88 ```toml 89 [[repos]] 90 name = "private-app" 91 url = "git@github.com:you/private-app.git" 92 description = "private work" 93 owner = "polymath" 94 ``` 95 96 Needs your SSH agent / keys available to the machine running xgit. 97 98 ### Local filesystem checkout (`path:`) 99 100 Publish this xgit project (or any other checkout on disk): 101 102 ```toml 103 [[repos]] 104 name = "xgit" 105 url = "path:." 106 description = "this project — static git page generator by polymath" 107 owner = "polymath" 108 ``` 109 110 `path:.` is relative to the directory that contains `config.toml`. 111 Absolute paths work too: `path:/home/you/code/myapp`. 112 113 ### Local seed demos 114 115 ```toml 116 [[repos]] 117 name = "workdir" 118 url = "local:workdir" 119 description = "from data/seed/workdir" 120 owner = "polymath" 121 ``` 122 123 Put a normal git checkout at `data/seed/workdir/` (or use `./demo` / `seed` for the built-in demos). 124 125 ### After config changes 126 127 ```bash 128 ./sync # fetch all [[repos]] + rebuild 129 ./serve --no-build # if already serving 130 ``` 131 132 Mirrors live in `data/repos/<name>.git`. Generated pages live in `html/<name>/`. 133 134 ## What the site includes 135 136 **Per repository** 137 138 - Log, Files, Refs 139 - Commit pages (diffstat + diff) 140 - Markdown render + Raw + Download 141 - Syntax-colored code + Raw + Download 142 - Atom feeds 143 144 **Site-wide** 145 146 - Index of all repos (owner links to author profile) 147 - Authors (same email → same profile + stats) 148 - Stats (totals, leaderboard, per-repo) 149 150 ## Develop / use as a project 151 152 This directory **is** the xgit git repository: 153 154 ```bash 155 git clone <your-xgit-remote> 156 cd xgit 157 ./demo 158 ``` 159 160 Optional install as a console script: 161 162 ```bash 163 pip install -e . 164 xgit sync 165 xgit serve 166 ``` 167 168 ## Layout 169 170 | Path | Role | 171 |------|------| 172 | `xgit/` | Library + CLI (`python -m xgit`) | 173 | `config.toml` | Your published repo list | 174 | `build` `serve` `sync` `demo` | Root runners | 175 | `data/` | Seeds + bare mirrors (ignored) | 176 | `html/` | Generated static site (ignored) | 177 178 ## License 179 180 BSD 2-Clause © polymath